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. Code Block |
---|
| http OPTIONS "https://vss-api.eis.utoronto.ca/v2/folder"
curl -X OPTIONS "https://vss-api.eis.utoronto.ca/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 GET "https://vss-api.eis.utoronto.ca/v2/folder" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/folder" |
Code Block |
---|
language | py |
---|
title | Response Body |
---|
collapse | true |
---|
|
{
"_links": {
"api":Folder Object | /folder/<moref> | Get logical folder attributes. | |
|
|
|
Folder Name | /folder/<moref>/name | Rename object. |
|
| |
|
Folder Children | /folder/<moref>/children | Get children folders if any. | |
|
|
|
Folder Parent | /folder/<moref>/parent | Get or move folder to a different parent. | |
| |
|
Folder VMs | /folder/<moref>/vm | List children virtual machines. | |
|
|
|
Folder Permission | /folder/<moref>/permission | List object permission. | |
|
|
|
Note |
---|
TK stores the Cloud API Token generated as a result of the following POST request to the /auth/request-token resource: Code Block |
---|
curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username> |
For example, extracting the token with the jq command: Code Block |
---|
TK=$(curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username> | jq -r '.token') |
|
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.
Code Block |
---|
http GET "https://vss-api.eis.utoronto.ca/v2/folder" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/",folder" |
The following examples implements HTTPie and CURL to list all folders a user have access to:
Code Block |
---|
language | py |
---|
title | Response Body |
---|
collapse | true |
---|
|
{
"_links": {
"self": "https://vss-api.eis.utoronto.ca/v2/folder?per_page=3&filter=path,like,%25Testing%25"
},
"data": [
{
"created_linkson": {
"2019-07-17 Wed 15:18:59 EDT",
"selfhas_children": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6736"false,
}"has_parent": true,
"full_pathmoref": "VSSgroup-v8923",
> Sandbox > jm > APIDemo", "moref"name": "group-v6736ut20170621092129",
"nameparent": "APIDemo", {
"parentmoref": "jm"group-v7350",
}, "name": "Testing",
{ "parent_linksmoref": {"group-v7349",
"selfpath": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6749"VSS > Development > Testing",
}, "vim_type": "vim.Folder"
"full_path": "VSS > Sandbox > jm > DockerDatacenter"},
"parent_moref": "group-v6749v7350",
"namepath": "DockerDatacenterVSS > Development > Testing > ut20170621092129",
"parentupdated_on": "jm"
2019-07-17 Wed 15:18:59 EDT",
} ], "vim_type": "metavim.Folder":
{ "count": 2,},
{
"time": "0.46083s", "usercreated_on": "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 | Enables 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 GET "https://vss-api.eis.utoronto.ca/v2/folder?name=API&summary=1" "Authorization: Bearer $TK"
http GET "https://vss-api.eis.utoronto.ca/v2/folder?moref=6736&summary=1" "Authorization: Bearer $TK"
http GET "https://vss-api.eis.utoronto.ca/v2/folder?parent=jm&summary=1" "Authorization: Bearer $TK" |
Code Block |
---|
language | py |
---|
title | Response Body |
---|
collapse | true |
---|
|
{
"_links": {2019-07-17 Wed 15:18:59 EDT",
"has_children": true,
"has_parent": true,
"moref": "group-v7350",
"name": "Testing",
"parent": {
"api": "https://vss-api.eis.utoronto.ca/v2/", "selfmoref": "https://vss-api.eis.utoronto.ca/v2/folder"group-v7349",
}, "data": [ "name": "Development",
{ "parent_linksmoref": {"group-v305",
"selfpath": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6736"
VSS > Development",
}, "vim_type": "vim.Folder"
"full_path": "VSS > Sandbox > jm > APIDemo"},
"parent_moref": "group-v6736v7349",
"namepath": "APIDemoVSS > Development > Testing",
"parentupdated_on": "jm"
2019-07-17 Wed 15:18:59 EDT",
} ], "meta": {"vim_type": "vim.Folder"
},
"count": 1, {
"time": "0.46083s", "usercreated_on": "jm"
2019-07-17 Wed 15:18:59 EDT",
"has_children": true,
}
} |
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 GET https://vss-api.eis.utoronto.ca/v2/folder/group-v6736&summary=1 "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET https://vss-api.eis.utoronto.ca/v2/folder/group-v6736&summary=1 |
HTTP response body would look something like:
Code Block |
---|
language | py |
---|
title | Response Body |
---|
collapse | true |
---|
|
{ "has_parent": true,
"moref": "group-v8900",
"_linksname": {"ut20170135153548",
"folder": "https://vss-api.eis.utoronto.ca/v2/folder",
"parent": {
"self": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6736" }, "datamoref": {"group-v7350",
"children": [ "name": "Testing",
{ "parent_linksmoref": {"group-v7349",
"path": "VSS > Development "self":> "http://localhost:5000/v2/folder/group-v6807"Testing",
},
"vim_type": "vim.Folder"
},
"name": "Templates"
}
],
"name"parent_moref": "APIDemogroup-v7350",
"parent": "jm", "path": "VSS > SandboxDevelopment > jmTesting > APIDemout20170135153548",
"vmCount": 7, "updated_on": "2019-07-17 Wed 15:18:59 EDT",
"vms "vim_type": ["vim.Folder"
}
{ ],
"meta": {
"_linkscount": {3,
"pages": {
"selffirst_url": "httphttps://localhost:5000/v2/vm/5012ee7a-bbb3-8fdb-c4e9-f87c658e3707"
}vss-api.eis.utoronto.ca/v2/folder?per_page=100&page=1&expand=True",
"name"last_url": "1605T-ecstatic_hopper"https://vss-api.eis.utoronto.ca/v2/folder?per_page=100&page=1&expand=True",
},"next_url": null,
"page": 1,
{ "pages": 1,
"_links": { "per_page": 100,
"selfprev_url": "http://localhost:5000/v2/vm/5012698f-5936-e4f3-c401-803b47aaebae"null,
"total": 3
}, },
"nametime": "1605T-condescending_pasteur"
}0.11766s",
"user": "jm"
{ "_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/v2/folder/group-v6736 "Authorization: Bearer $TK" name=APISubFolder
curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X POST https://vss-api.eis.utoronto.ca/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 |
---|
language | py |
---|
title | Response Body |
---|
collapse | true |
---|
|
{
"data": {
"_links": {
"request":}
} |
Paging
All requests to the /folder URL are paginated. The response body includes a 'meta.pages' key with everything to navigate through the results, for instance:
Key | Description |
---|
first_url | Contain the URLs to navigate through results. |
last_url |
prev_url |
next_url |
page | Current page |
pages | Total number of pages |
per_page | Results per page. Maximum 250; Default 10. |
total | Total number of results |
Results per page can be set by including the parameter in the URL query, so we can get the desired number of elements per page, for example:
Code Block |
---|
http GET "https://vss-api.eis.utoronto.ca/v2/folder?per_page=1" "Authorization: Bearer $TK"
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/request/folder/2",
"task": "https://vss-api.eis.utoronto.ca/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 |
---|
language | py |
---|
title | Response Body |
---|
collapse | true |
---|
|
{
"_links": {
"api":?per_page=1" |
Filtering
Folders can be filtered by adding the filter argument to the query string in the following format:
Code Block |
---|
filter=<field_name>,<operator>,<value> |
Operators can be:
Operator | Description |
---|
eq | Equals |
ne | Not equal |
lt | Lower than |
le | Lower equal |
gt | Greater than |
ge | Greater equal |
like | Matching pattern |
in | Match value in many items separated by commas |
A resource can be filtered by as many attributes the request has, for instance /folder can be filtered by moref, path, created_on, name, etc. Thus, the following example will filter only by name=Prod
Code Block |
---|
http GET "https://vss-api.eis.utoronto.ca/v2/folder?per_page=10&expand=1&filter=name,like,%Prod%" "Authorization: Bearer $TK" |
Sorting
The resource provides also attribute sorting by adding the sort parameter in the URL query string in the following format:
Code Block |
---|
sort=<field_name>,<asc|desc> |
The following example shows how to filter by label:
Code Block |
---|
http GET "https://vss-api.eis.utoronto.ca/v2/folder?per_page=10&expand=1&filter=name,like,%Prod%&sort=label,desc" "Authorization: Bearer $TK"
curl -X GET -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/",
"self": "https://vss-api.eis.utoronto.ca/v2/folder"
},
"data": [
{
"_links": {
"self": "/v2/network?per_page=10&expand=1&filter=name,like,%VL%&sort=label,desc" |
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/v2/folder/group-v6899v6736 "Authorization: Bearer $TK" name=APISubFolder
},
"full_path": "VSS > Sandbox > jm > APIDemo > APISubFolder",
"moref": "group-v6899",
"name": "APISubFolder",
"parent": "APIDemo"
},
{
curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X POST https://vss-api.eis.utoronto.ca/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 |
---|
language | py |
---|
title | Response Body |
---|
collapse | true |
---|
|
{
"data": {
"_links": {
"selfrequest": "https://vss-api.eis.utoronto.ca/v2/request/folder/group-v6736"
}2",
"full_pathtask": "VSS > Sandbox > jm > APIDemo",https://vss-api.eis.utoronto.ca/v2/request/task/fff43ba4-40c1-40df-bf5b-02f5424e091a"
},
"morefmessage": "group-v6736",
VM Folder creation request has been accepted for processing",
"name": "APIDemoAccepted",
"parentstate": "jmSubmitted",
"status": }202
]},
"meta": {
"count": 2,
"time": "0.55448s07877s",
"user": "jm"
}
} |
Update
Renaming or moving folders between your folder tree is possible by making a PUT request to the URI folder in question sending both the attribute and value you wish to update. Currently, we support name and parent as supported attributes.
Attribute | Description |
---|
name | folder new name |
parent | managed object reference of new parent folder |
The following request illustrates how to update a folder's name (group-v6736) to NewAPIFolder:
Code Block |
---|
http PUT https://vss-api.eis.utoronto.ca/v2/folder/group-v6736 "Authorization: Bearer $TK" attribute="name" value="NewAPIFolder"
curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X PUT https://vss-api.eis.utoronto.ca/v2/folder/group-v6736 -d '{"attribute": "name", "value": "NewAPIFolder"}' |
HTTP response would look something like:
Code Block |
---|
|
HTTP/1.1 202 ACCEPTED
Allow: HEAD, GET, PUT, POST, OPTIONS
Connection: keep-alive
Content-Length: 437
Content-Type: application/json
Date: Mon, 27 Jun 2016 14:38:32 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/d7eec47d-fd14-4958-a5ff-bfb93a191a01
Server: nginx
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2996
X-RateLimit-Reset: 1467039600 |
Code Block |
---|
language | py |
---|
title | Response Body |
---|
collapse | true |
---|
|
{
"data": {
"_links": {
"request": "https://vss-api.eis.utoronto.ca/v2/request/folder/3",
"task": "https://vss-api.eis.utoronto.ca/v2/request/task/d7eec47d-fd14-4958-a5ff-bfb93a191a01"
},
"message": "VM Folder change request has been accepted for processing",
"name": "Accepted",
"state": "Submitted",
"status": 202
},
"meta": {
"time": "0.39327s",
"user": "jm"
}
} |
Tip |
---|
If you wish to update any parent folder, just select the new parent moref and include it in the PUT request attribute's value, i.e. Code Block |
---|
http PUT https://vss-api.eis.utoronto.ca/v2/folder/group-v6736 "Authorization: Bearer $TK" attribute="parent" value="group-v1234"
curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X PUT https://vss-api.eis.utoronto.ca/v2/folder/group-v6736 -d '{"attribute": "parent", "value": "group-v1234""}' |
Where group-v1234 would be new parent of group-v6736 |