Introduction
Logical Folders are containers for storing and organizing inventory objects, in this case virtual machines. As the network resource, a Folder has a Managed Object Reference (moref) which is required for either virtual machine deployment (where a virtual machine will be placed upon creation) or updating virtual machine containing folder (moved).
The /v2/folder resource lists folders you are allowed to access in our environment. If by any chance you cannot see a folder and you add it to a new virtual machine creation request or a virtual machine change request, they will not be successfully processed. If you believe you need access to a specific folder, please let us know.
Panel | ||||||
---|---|---|---|---|---|---|
On this page:
|
The following table shows a brief description and HTTP methods allowed to interact with logical folders.
Resource | URI | Description | GET | POST | PUT | PATCH | OPTIONS |
---|---|---|---|---|---|---|---|
Folder | /folder | Logical Folder Management resource. List permitted folders and their attributes |
Note | |||||
---|---|---|---|---|---|
| |||||
Remember, you can also show what methods are allowed and method description, parameters, etc. by making an OPTIONS HTTP request to /v2/folder.
|
List
In order to list allowed Folders you should make a GET request to the endpoint /v2/folder, passing your access token. As a result, you will get a reference URI /v2/folder/<moref> to get detailed information about that folder, human readable name and Managed Object Reference (moref).
Name | Type | Description |
---|---|---|
name | string | Folder name. |
parent | string | Parent folder name. |
moref | string | vCenter Managed Object Reference (moref) |
_links | array | List of URIs related to the resource. |
full_path | string | vCenter full path to the folder |
The following examples implements HTTPie and CURL to list all folders a user have access to:
Code Block |
---|
http -a $TK GET "https://vss-api.eis.utoronto.ca:8001/v2/folder" curl -u $TK -X GET "https://vss-api.eis.utoronto.ca:8001/v2/folder" |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "_links": { "api": "https://vss-api.eis.utoronto.ca:8001/v2/", "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder" }, "data": [ { "_links": { "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6736" }, "full_path": "VSS > Sandbox > jm > APIDemo", "moref": "group-v6736", "name": "APIDemo", "parent": "jm" }, { "_links": { "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6749" }, "full_path": "VSS > Sandbox > jm > DockerDatacenter", "moref": "group-v6749", "name": "DockerDatacenter", "parent": "jm" } ], "meta": { "count": 2, "time": "0.46083s", "user": "jm" } } |
Filters
This resource has two main filters to narrow down the number of Networks shown in the result.
Name | Description |
---|---|
name | Folder name |
moref | vCenter Managed Object Reference (moref) |
parent | Parent folder name |
summary | Disable folder summary data |
The following examples show how to make a GET request, which in both cases, the result would be the same because APIDemo moref contains number 6379.
Code Block |
---|
http -a $TK GET "https://vss-api.eis.utoronto.ca:8001/v2/folder?name=API" http -a $TK GET "https://vss-api.eis.utoronto.ca:8001/v2/folder?moref=6736" http -a $TK GET "https://vss-api.eis.utoronto.ca:8001/v2/folder?parent=jm" |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "_links": { "api": "https://vss-api.eis.utoronto.ca:8001/v2/", "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder" }, "data": [ { "_links": { "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6736" }, "full_path": "VSS > Sandbox > jm > APIDemo", "moref": "group-v6736", "name": "APIDemo", "parent": "jm" } ], "meta": { "count": 1, "time": "0.46083s", "user": "jm" } } |
List specific folder info
Some of the attributes will have an object value. Such is the case of items in attribute vms.
Name | Type | Description |
---|---|---|
vms | array | Array of Virtual Machines in folder. |
vmCount | integer | Number of virtual machines in folder |
children | object | Immediate children folders |
The following example, requests information about a particular Folder using the base resource /v2/folder and appending the moref to get the URI /v2/folder/group-v6736:
Code Block |
---|
http -a $TK GET https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6736 curl -u $TK -X GET https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6736 |
HTTP response body would look something like:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "_links": { "folder": "https://vss-api.eis.utoronto.ca:8001/v2/folder", "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6736" }, "data": { "children": [ { "_links": { "self": "http://localhost:5000/v2/folder/group-v6807" }, "name": "Templates" } ], "name": "APIDemo", "parent": "jm", "path": "VSS > Sandbox > jm > APIDemo", "vmCount": 7, "vms": [ { "_links": { "self": "http://localhost:5000/v2/vm/5012ee7a-bbb3-8fdb-c4e9-f87c658e3707" }, "name": "1605T-ecstatic_hopper" }, { "_links": { "self": "http://localhost:5000/v2/vm/5012698f-5936-e4f3-c401-803b47aaebae" }, "name": "1605T-condescending_pasteur" }, { "_links": { "self": "http://localhost:5000/v2/vm/50126aab-84c4-c532-871b-a431fc47f1e1" }, "name": "1605T-kickass_blackwell" }, { "_links": { "self": "http://localhost:5000/v2/vm/50124198-bc0b-add7-aea4-b36c3dc0dc49" }, "name": "1605T-naughty_mcclintock" }, { "_links": { "self": "http://localhost:5000/v2/vm/50123bea-a643-755c-cd8a-24bc852ee3c5" }, "name": "1605T-ecstatic_mclean" }, { "_links": { "self": "http://localhost:5000/v2/vm/50126185-ebb2-36ec-bca8-476e51bfe0c8" }, "name": "1605T-kickass_sinoussi" }, { "_links": { "self": "http://localhost:5000/v2/vm/5012ea31-b0ae-2975-2e9f-d7b7c3bb3622" }, "name": "1605T-boring_goodall" } ] }, "meta": { "count": 5, "time": "0.42114s", "user": "jm" } } |
Create
To create a new folder you just need to submit a request to /v2/folder/<moref> and provide the name of the new folder as a parameter. So, the folder <moref> will be parent of the new folder. For this example we will create a subfolder in APIDemo > APISubFolder, so request will be crafted as follows:
Code Block |
---|
http -a $TK POST https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6736 name=APISubFolder
curl -H "Content-Type: application/json" -u $TK -X POST https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6736 -d '{"name": "APISubFolder"}' |
Code Block | ||
---|---|---|
| ||
HTTP/1.1 202 ACCEPTED Allow: POST, HEAD, OPTIONS, GET Connection: keep-alive Content-Length: 400 Content-Type: application/json Date: Wed, 11 May 2016 17:19:15 GMT Location: https://vss-api.eis.utoronto.ca/v2/request/task/fff43ba4-40c1-40df-bf5b-02f5424e091a Server: nginx X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2997 X-RateLimit-Reset: 1462989600 |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "data": { "_links": { "request": "https://vss-api.eis.utoronto.ca:8001/v2/request/folder/2", "task": "https://vss-api.eis.utoronto.ca:8001/v2/request/task/fff43ba4-40c1-40df-bf5b-02f5424e091a" }, "message": "VM Folder creation request has been accepted for processing", "name": "Accepted", "state": "Submitted", "status": 202 }, "meta": { "time": "0.07877s", "user": "jm" } } |
Listing folder
Listing folders with the API word in them, would show the folder has been successfully created:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "_links": { "api": "https://vss-api.eis.utoronto.ca:8001/v2/", "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder" }, "data": [ { "_links": { "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6899" }, "full_path": "VSS > Sandbox > jm > APIDemo > APISubFolder", "moref": "group-v6899", "name": "APISubFolder", "parent": "APIDemo" }, { "_links": { "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6736" }, "full_path": "VSS > Sandbox > jm > APIDemo", "moref": "group-v6736", "name": "APIDemo", "parent": "jm" } ], "meta": { "count": 2, "time": "0.55448s", "user": "jm" } } |