Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

Logical Folders are containers for storing and organizing inventory objects, in this case virtual machines. Just like 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 (move).

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:

Table of Contents
maxLevel2
outlinetrue


The following table shows a brief description and HTTP methods allowed to interact with logical folders.

ResourceURIDescriptionGETPOSTPUTPATCHOPTIONS
Folder/folderLogical Folder Management resource. List permitted folders and their attributes(tick)(tick) (tick)(tick) (tick)(tick)(tick)
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 '.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, human readable name and Managed Object Reference (moref).

NameTypeDescriptionnamestringFolder name.parentstringParent folder name.morefstringvCenter Managed Object Reference (moref)_linksarrayList of URIs related to the resource.pathstringvCenter full path to the folder

The following examples implements HTTPie and CURL to list all folders a user have access to:

Code Blockhttp GET "

Folder Object/folder/<moref>Get logical folder attributes.(tick) 


Folder Name/folder/<moref>/nameRename object.

(tick) 
Folder Children/folder/<moref>/childrenGet children folders if any.(tick) 


Folder Parent/folder/<moref>/parentGet or move folder to a different parent.(tick)
(tick) 
Folder VMs/folder/<moref>/vmList children virtual machines.(tick) 


Folder Permission/folder/<moref>/permissionList object permission.(tick) 



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/
v2/folder?summary=1" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/folder?summary=1"
Code Block
languagepy
titleResponse Body
collapsetrue
{ "_links": { "api": "
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"  "self":-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
languagepy
titleResponse Body
collapsetrue
{
    },
    "data"_links": [{
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6736?per_page=3&filter=path,like,%25Testing%25"
    },
    "data": [
 },       {
     "path": "VSS > Sandbox > jm > APIDemo       "created_on": "2019-07-17 Wed 15:18:59 EDT",
            "morefhas_children": "group-v6736"false,
            "namehas_parent": "APIDemo"true,
            "parentmoref": "jmgroup-v8923",
        },    "name": "ut20170621092129",
   {             "_links""parent": {
                "selfmoref": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6749"
     v7350",
      },             "full_path"name": "Testing"VSS,
> Sandbox > jm > DockerDatacenter",             "parent_moref": "group-v6749v7349",
                "namepath": "DockerDatacenterVSS > Development > Testing",
                "parentvim_type": "jmvim.Folder"
        }     ]},
    "meta": {
        "countparent_moref": 2,"group-v7350",
            "timepath": "0.46083s",
    VSS > Development > Testing > ut20170621092129",
   "user": "jm"     }
}

Filters

This resource has two main filters to narrow down the number of Networks shown in the result.

NameDescriptionnameFolder namemorefvCenter Managed Object Reference (moref)parentParent folder namesortSort results by name, moref or parentsummaryEnables 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
languagepy
titleResponse Body
collapsetrue
{
    "_links": {   "updated_on": "2019-07-17 Wed 15:18:59 EDT",
            "vim_type": "vim.Folder"
        },
        {
            "created_on": "2019-07-17 Wed 15:18:59 EDT",
            "has_children": true,
            "has_parent": true,
            "moref": "group-v7350",
            "name": "Testing",
            "parent": {
                "apimoref": "https://vss-api.eis.utoronto.ca/v2/",group-v7349",
                "selfname": "https://vss-api.eis.utoronto.ca/v2/folder"Development",
    },     "data": [      "parent_moref": "group-v305",
 {               "_linkspath": {
"VSS > Development",
                "selfvim_type": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6736vim.Folder"
            },
            "fullparent_pathmoref": "VSS > Sandbox > jm > APIDemogroup-v7349",
            "morefpath": "group-v6736VSS > Development > Testing",
            "nameupdated_on": "APIDemo"2019-07-17 Wed 15:18:59 EDT",
            "parentvim_type": "jmvim.Folder"
        },
    ],    {
  "meta": {         "count": 1"created_on": "2019-07-17 Wed 15:18:59 EDT",
        "time    "has_children": "0.46083s"true,
         "user   "has_parent": true,
            "moref": "jm"group-v8900",
            "name": "ut20170135153548",
} }

List specific folder info

Some of the attributes will have an object value. Such is the case of items in attribute vms.

NameTypeDescription
vmsarrayArray of Virtual Machines in folder.
vmCountintegerNumber of virtual machines in folder
childrenobjectImmediate 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
languagepy
titleResponse Body
collapsetrue
{
    "_links": {
        "folder": "https://vss-api.eis.utoronto.ca/v2/folder",
        "self": "https://vss-api.eis.utoronto.ca/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": {
                    "selfparent": "http://localhost:5000/v2/vm/50123bea-a643-755c-cd8a-24bc852ee3c5"{
                 }"moref": "group-v7350",
                "name": "1605T-ecstatic_mcleanTesting",
            },       "parent_moref": "group-v7349",
     {                 "_links"path": {"VSS > Development > Testing",
                "selfvim_type": "http://localhost:5000/v2/vm/50126185-ebb2-36ec-bca8-476e51bfe0c8vim.Folder"
                },
  
             "nameparent_moref": "1605Tgroup-kickass_sinoussiv7350",
            },
            {
 "path": "VSS > Development > Testing > ut20170135153548",
              "updated_linkson": {
  "2019-07-17 Wed 15:18:59 EDT",
            "vim_type": "vim.Folder"
   "self": "http://localhost:5000/v2/vm/5012ea31-b0ae-2975-2e9f-d7b7c3bb3622"    }
    ],
    "meta": {
 },       "count": 3,
        "namepages": "1605T-boring_goodall"{
            }
   "first_url": "https://vss-api.eis.utoronto.ca/v2/folder?per_page=100&page=1&expand=True",
    ]     },     "metalast_url": {"https://vss-api.eis.utoronto.ca/v2/folder?per_page=100&page=1&expand=True",
        "count": 5,
        "time"next_url": "0.42114s",
  null,
     "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
titleRespoonse Headers
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
languagepy
titleResponse Body
collapsetrue
{
    "data": {
        "_links": {
            "request":  "page": 1,
            "pages": 1,
            "per_page": 100,
            "prev_url": null,
            "total": 3
        },
        "time": "0.11766s",
        "user": "jm"
    }
}

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:

KeyDescription
first_urlContain the URLs to navigate through results.
last_url
prev_url
next_url
pageCurrent page
pagesTotal number of pages
per_pageResults per page. Maximum 250; Default 10.
totalTotal 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
languagepy
titleResponse Body
collapsetrue
{
    "_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:

OperatorDescription
eqEquals
neNot equal
ltLower than
leLower equal
gtGreater than
geGreater equal
likeMatching pattern
inMatch 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
titleRespoonse Headers
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
languagepy
titleResponse Body
collapsetrue
{
    "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. 

AttributeDescription
namefolder new name
parentmanaged 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
titleRespoonse Headers
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
languagepy
titleResponse Body
collapsetrue
{
    "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