Versions Compared

Old Version 7

changes.mady.by.user JM Lopez

Saved on

compared with

New Version 8

changes.mady.by.user JM Lopez

Saved on

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

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)
Note
titleOPTIONS 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
languagebash
http OPTIONS "https://vss-api.eis.utoronto.ca:8001/v2/folder"
curl -X OPTIONS "https://vss-api.eis.utoronto.ca:8001/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).

NameTypeDescription
namestringFolder name.
parentstringParent folder name.
morefstringvCenter Managed Object Reference (moref)
_linksarrayList of URIs related to the resource.
full_pathstringvCenter 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
languagepy
titleResponse Body
collapsetrue
{
    "_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.

NameDescription
NamenameFolder name
morefvCenter Managed Object Reference (moref)
parentParent folder name
summaryDisable 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
languagepy
titleResponse Body
collapsetrue
{
    "_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.

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 -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
languagepy
titleResponse Body
collapsetrue
{
    "_links": {
        "folder": "https://vss-api.eis.utoronto.ca:8001/v2/folder",
        "self": "https://vss-api.eis.utoronto.ca:8001/v2/folder/group-v6736"
    },
    "data": {
        "namechildren": "APIDemo", [
            {
      "parent": "jm",         "path_links": "VSS > Sandbox > jm > APIDemo", {
                    "self"vmCount": 2,: "http://localhost:5000/v2/folder/group-v6807"
         "vms": [       },
                "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": {
                    "hrefself": "httpshttp://vss-api.eis.utoronto.ca:8001localhost:5000/v2/vm/501269e650126185-2c49ebb2-ecda36ec-fdc0bca8-862693465325476e51bfe0c8"
                },
                "name": "1605T-lovingkickass_wilsonsinoussi"
            },
            {
                "_links": {
                    "hrefself": "httpshttp://vss-api.eis.utoronto.ca:8001localhost:5000/v2/vm/50124dc25012ea31-aba4b0ae-5c572975-130c2e9f-da207557e5bdd7b7c3bb3622"
                },
                "name": "1605T-sickboring_stallmangoodall"
            }
        ]
    },
    "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 -u $TK -X POST https://vss-api.eis.utoronto.ca:8001/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": "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
languagepy
titleResponse Body
collapsetrue
{
    "_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"
    }
}