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

maxLevel	2
outline	true

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

http OPTIONS "

TK stores the Cloud API Token generated as a result of the following POST request to the /auth/request-token resource:

Note

title	OPTIONS HTTP method

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

language	bash

Code Block
curl -X POST https://vss-api.eis.utoronto.ca/v2/folder" auth/request-token -u <username>

For example, extracting the token with the jq command:

Code Block
TK=$(curl -X OPTIONSPOST "https://vss-api.eis.utoronto.ca/v2/folder"

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).

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.
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?summary=1" "Authorization: Bearer $TK" curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/folder?summary=1"

Code Block

language	py
title	Response Body
collapse	true

{
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2/",
        "self": "https://vss-api.eis.utoronto.ca/v2/folder"
    },
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/v2/folder/group-v6736"
            },
            "path": "VSS > Sandbox > jm > APIDemo",
            "moref": "group-v6736",
            "name": "APIDemo",
            "parent": "jm"
        },
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/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
sort	Sort results by name, moref or parent
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": {
        "api": "https://vss-api.eis.utoronto.ca/v2/",
        "self": "https://vss-api.eis.utoronto.ca/v2/folder"
    },
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/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 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

{
    "_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": {
                    "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

title	Respoonse 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

language	py
title	Response Body
collapse	true

{
    "data": {
        "_links": {
            "request": "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": "https://vss-api.eis.utoronto.ca/v2/",
        "self": "https://vss-api.eis.utoronto.ca/v2/folder"
    },
    "data": [
        {
            "_links": {
                "self": "https://vss-api.eis.utoronto.ca/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/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"
    }
}

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

title	Respoonse 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

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

Versions Compared

Old Version 17

New Version 18

Key

Introduction

List

Filters

List specific folder info

Create

Listing folder

Update

Page Comparison

Versions Compared

Old Version 17

New Version 18

Key

Introduction

List

Filters

List specific folder info

Create

Listing folder

Update