Introduction

The ITS Private Cloud API introduces a new “VM Service tagging” feature, which is now a mandatory attribute for ITS managed VMs and it allows ITS VM owners to more easily manage and identify the VM’s role with its associated services.

By using the Cloud API, ITS VM admins can tag the services to their VMs by simply selecting a matching service from a pre-populated list of components which is automatically imported from the ITS System Status Page by the Cloud API.

Panel

On this page:

Table of Contents

outline	true

Resource	URI	Description	GET	POST	PUT	PATCH
VSS Service	/vss/service	VSS Service resource. List existing ITS System Status Page components.
VSS Service Group	/vss/service-group	VSS Service Group resource. List existing ITS System Status Page component group.

List

To list a summary of all available Services, make a GET request to /vss/service resource as follows:

http -a $TK

Code Block

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

To list a summary of all available Services, make a GET request to /vss/service resource as follows:

Code Block
curl -H "Authorization: Bearer $TK" -X GET https://vss-api.eis.utoronto.ca/v2/vss/service http GET https://vss-api.eis.utoronto.ca/v2/vss/service "Authorization: Bearer $TK"

Code Block

language	py
title	Response Body
collapse	true

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vss/service"
    },
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/vss/service/1",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/3",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/4",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/9",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/6",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/7",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/8",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/2",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/10",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/11"
    ],
    "meta": {
        "count": 10,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=10&page=12",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=10&page=2",
            "page": 1,
            "pages": 12,
            "per_page": 10,
            "prev_url": null,
            "total": 113
        },
        "time": "0.01075s",
        "user": "josem"
    }
}

Note
The meta key contains a new element called pages which controls paging and many other features listed below.

Paging

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 100; 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 Blockhttp -a $TK

:

Code Block
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=5" http GET "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=5" "Authorization: Bearer $TK"

Code Block

language	py
title	Response Body
collapse	true

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=5"
    },
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/vss/service/1",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/3",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/4",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/9",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/6"
    ],
    "meta": {
        "count": 5,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=5&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=5&page=23",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=5&page=2",
            "page": 1,
            "pages": 23,
            "per_page": 5,
            "prev_url": null,
            "total": 113
        },
        "time": "0.00926s",
        "user": "josem"
    }
}

In this example, you can see the number of pages have increased from 12 to 23 and the '_link.self' key has included the parameter 'per_page' in the URL query.

Expansion

VSS Service resource expansion is disabled by default, therefore elements found are listed as URLs. However, if you wish to display its contents add the expand=1 to URL query string and you will get the actual element in full JSON format, as follows:

Code Blockhttp -a $TK

:

Code Block

curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=1&page=22&expand=1"

http GET "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=1&page=22&expand=1" "Authorization: Bearer $TK"

Code Block

language	py
title	Response Body
collapse	true

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=1&page=22&expand=1"
    },
    "data": [
        {
            "created_on": "2019-03-11T19:27:25.758271Z",
            "description": "Employee Self-Service",
            "group": {
                "description": null,
                "id": 3,
                "name": "Administrative Web Services"
            },
            "id": 16,
            "label": "Administrative Web Services/ESS",
            "name": "ESS",
            "updated_on": "2019-04-15T16:28:22.899755Z"
        }
    ],
    "meta": {
        "count": 1,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=1&page=1&expand=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=1&page=113&expand=1",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=1&page=23&expand=1",
            "page": 22,
            "pages": 113,
            "per_page": 1,
            "prev_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=1&page=21&expand=1",
            "total": 113
        },
        "time": "0.01093s",
        "user": "josem"
    }
}

Filtering

VSS Services 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 object has, for instance /vss/service can be filtered by label, name, description, etc. Thus, the following example will filter VSS Services with label like Administrative Web Services.

Code Block

http -a $TKcurl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,Administrative Web Services%"

http GET "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,Administrative Web Services%" "Authorization: Bearer $TK"

Code Block

language	py
title	Response Body
collapse	true

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,Administrative Web Services%"
    },
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/vss/service/22",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/28",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/27",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/26",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/25",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/24",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/23",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/21",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/20",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/19"
    ],
    "meta": {
        "count": 10,
        "filter": "label,like,Administrative Web Services%",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label%2Clike%2CAdministrative+Web+Services%25&per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label%2Clike%2CAdministrative+Web+Services%25&per_page=10&page=2",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label%2Clike%2CAdministrative+Web+Services%25&per_page=10&page=2",
            "page": 1,
            "pages": 2,
            "per_page": 10,
            "prev_url": null,
            "total": 20
        },
        "time": "0.00980s",
        "user": "josem"
    }
}

Using additional filters is possible by adding the ";" character as follows:

Code Block

http -a $TKcurl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,Administrative Web Services%;name,like,uSOURCE%"

http GET "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,Administrative Web Services%;name,like,uSOURCE%" "Authorization: Bearer $TK"

Code Block

language	py
title	Response Body
collapse	true

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label,like,Administrative Web Services%%3Bname,like,uSOURCE%"
    },
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/vss/service/25"
    ],
    "meta": {
        "count": 1,
        "filter": "label,like,Administrative Web Services%;name,like,uSOURCE%",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label%2Clike%2CAdministrative+Web+Services%25%3Bname%2Clike%2CuSOURCE%25&per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?filter=label%2Clike%2CAdministrative+Web+Services%25%3Bname%2Clike%2CuSOURCE%25&per_page=10&page=1",
            "next_url": null,
            "page": 1,
            "pages": 1,
            "per_page": 10,
            "prev_url": null,
            "total": 1
        },
        "time": "0.00468s",
        "user": "josem"
    }
}

Sorting

VSS Services can be sorted 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 date (latest first):

Code Block

curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=10&sort=label,asc"

http GET "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=10&sort=label,asc" "Authorization: Bearer $TK"

Code Block

language	py
title	Response Body
collapse	true

{
    "_links": {
        "self": "https://vss-api.eis.utoronto.ca/v2/vss/service?per_page=10&sort=label,asc"
    },
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/vss/service/8",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/5",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/6",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/7",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/9",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/10",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/11",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/12",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/13",
        "https://vss-api.eis.utoronto.ca/v2/vss/service/14"
    ],
    "meta": {
        "count": 10,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?sort=label%2Casc&per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?sort=label%2Casc&per_page=10&page=12",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/vss/service?sort=label%2Casc&per_page=10&page=2",
            "page": 1,
            "pages": 12,
            "per_page": 10,
            "prev_url": null,
            "total": 113
        },
        "sort": "label,asc",
        "time": "0.01205s",
        "user": "josem"
    }
}

Versions Compared

Old Version 2

New Version Current

Key

Introduction

List

List

Expansion

Filtering

Sorting

Page Comparison

Versions Compared

Old Version 2

New Version Current

Key

Introduction

List

List

Expansion

Filtering

Sorting