Introduction

The /v2/request resource provides the list of submitted requests, including change, new, export, inventory, folder, snapshot, etc. With this resource you can get further details about a virtual machine creation, specifically what Uuid this VM was assigned upon creation or if it failed, what was the reason.

Resource	URI	Description	GET	POST	PUT	DELETE
Request	/request	Request Management resource.

On this page:

Child pages:

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

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

For example, extracting the token with the jq command:

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 your requests, do a GET request to /request resource as follows:

http GET https://vss-api.eis.utoronto.ca/v2/request "Authorization: Bearer $TK"

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

Response Body

{
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2/",
        "change": "https://vss-api.eis.utoronto.ca/v2/request/change",
        "export": "https://vss-api.eis.utoronto.ca/v2/request/export",
        "folder": "https://vss-api.eis.utoronto.ca/v2/request/folder",
        "inventory": "https://vss-api.eis.utoronto.ca/v2/request/inventory",
        "new": "https://vss-api.eis.utoronto.ca/v2/request/new",
        "self": "https://vss-api.eis.utoronto.ca/v2/request",
        "snapshot": "https://vss-api.eis.utoronto.ca/v2/request/snapshot"
    },
    "data": {
        "change": 33,
        "export": 2,
        "folder": 2,
        "inventory": 4,
        "new": 21,
        "snapshot": 1
    },
    "meta": {
        "count": 6,
        "time": "0.01528s",
        "user": "josem"
    }
}

Available request resources are listed in '_links' key, such as change, export, folder, inventory, new and snapshot. Those can be accessed by just making a GET request to the given URL, for instance getting all available snapshot requests is done as follows:

http GET https://vss-api.eis.utoronto.ca/v2/request/snapshot "Authorization: Bearer $TK"

curl -X GET -H "Authorization: Bearer $TK" https://vss-api.eis.utoronto.ca/v2/request/snapshot

Response Body

{
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/request/snapshot/1"
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/request/snapshot"
        },
        "count": 1,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/request/snapshot?per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/request/snapshot?per_page=10&page=1",
            "next_url": null,
            "page": 1,
            "pages": 1,
            "per_page": 10,
            "prev_url": null,
            "total": 1
        },
        "time": "0.00839s",
        "user": "josem"
    }
}

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

Paging

All requests to the /request/<type> URL are paginated. The response body includes a 'meta.pages' key with everything to navigate through the results, for instance:

Meta key

    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/request/change"
        },
        "count": 10,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=10&page=4",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=10&page=2",
            "page": 1,
            "pages": 4,
            "per_page": 10,
            "prev_url": null,
            "total": 33
        },
        "time": "0.01463s",
        "user": "josem"
    }

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:

http GET https://vss-api.eis.utoronto.ca/v2/request/change?per_page=5 "Authorization: Bearer $TK"

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

Response Body

{
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/request/change/17",
        "https://vss-api.eis.utoronto.ca/v2/request/change/22",
        "https://vss-api.eis.utoronto.ca/v2/request/change/20",
        "https://vss-api.eis.utoronto.ca/v2/request/change/21",
        "https://vss-api.eis.utoronto.ca/v2/request/change/23"
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=5"
        },
        "count": 5,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=5&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=5&page=7",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=5&page=2",
            "page": 1,
            "pages": 7,
            "per_page": 5,
            "prev_url": null,
            "total": 33
        },
        "time": "0.01349s",
        "user": "josem"
    }
}

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

Expansion

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

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

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

Response Body

{
    "data": [
        {
            "attribute": "net",
            "created_on": "2016-07-06 12:15:03 EDT",
            "id": 77,
            "message": {
                "errors": [],
                "warnings": [
                    "Virtual NIC 2 changed to E1000e"
                ]
            },
            "scheduled": null,
            "scheduled_datetime": null,
            "status": "PROCESSED",
            "task_id": "586d338d-abfb-4e4e-9391-5a28a87a4707",
            "updated_on": "2016-07-06 12:15:03 EDT",
            "user": {
                "_links": {
                    "self": "https://vss-api.eis.utoronto.ca/v2/user"
                },
                "username": "josem"
            },
            "user_id": 2,
            "value": {
                "property": "type",
                "type": "E1000e",
                "unit": 2
            },
            "vm_name": "<vm_name>",
            "vm_uuid": "<vm_uuid>
        }
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=1&expand=1&page=22"
        },
        "count": 1,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=1&page=1&expand=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=1&page=33&expand=1",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=1&page=23&expand=1",
            "page": 22,
            "pages": 33,
            "per_page": 1,
            "prev_url": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=1&page=21&expand=1",
            "total": 33
        },
        "time": "0.01134s",
        "user": "josem"
    }
}

Filtering

Requests can be filtered by adding the filter argument to the query string in the following format:

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 /request/change can be filtered by attribute, created_on, scheduled, scheduled_datetime, updated_on, vm_name, vm_uuid, etc. Thus, the following example will filter change requests with status equals to Error Processed

http GET "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status,eq,ERROR" "Authorization: Bearer $TK"

curl -X GET -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status,eq,ERROR"

Response Body

{
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/request/change/22",
        "https://vss-api.eis.utoronto.ca/v2/request/change/78",
        "https://vss-api.eis.utoronto.ca/v2/request/change/140",
        "https://vss-api.eis.utoronto.ca/v2/request/change/206",
        "https://vss-api.eis.utoronto.ca/v2/request/change/203",
        "https://vss-api.eis.utoronto.ca/v2/request/change/207"
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status,eq,ERROR"
        },
        "count": 6,
        "filter": "status,eq,ERROR",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status%2Ceq%2ERROR&per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status%2Ceq%2ERROR&per_page=10&page=1",
            "next_url": null,
            "page": 1,
            "pages": 1,
            "per_page": 10,
            "prev_url": null,
            "total": 6
        },
        "time": "0.00941s",
        "user": "josem"
    }
}

Filtering change requests made after 2016-07-10 is done by adding another filter with the ";" character as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status,eq,ERROR;created_on,gt,2016-07-10" "Authorization: Bearer $TK"

curl -X GET -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status,eq,ERROR;created_on,gt,2016-07-10"

Response Body

{
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/request/change/140",
        "https://vss-api.eis.utoronto.ca/v2/request/change/206",
        "https://vss-api.eis.utoronto.ca/v2/request/change/203",
        "https://vss-api.eis.utoronto.ca/v2/request/change/207"
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status,eq,ERROR%3Bcreated_on,gt,2016-07-10"
        },
        "count": 4,
        "filter": "status,eq,ERROR;created_on,gt,2016-07-10",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status%2Ceq%2CERROR%3Bcreated_on%2Cgt%2C2016-07-10&per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/request/change?filter=status%2Ceq%2CERROR%3Bcreated_on%2Cgt%2C2016-07-10&per_page=10&page=1",
            "next_url": null,
            "page": 1,
            "pages": 1,
            "per_page": 10,
            "prev_url": null,
            "total": 4
        },
        "time": "0.00951s",
        "user": "josem"
    }
}

Sorting

Requests can be sorted by adding the sort parameter in the URL query string in the following format:

sort=<field_name>,<asc|desc>

The following example shows how to filter by date (latest first):

http GET "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=10&sort=created_on,desc" "Authorization: Bearer $TK"

curl -X GET -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=10&sort=created_on,desc"

Response Body

{
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/request/change/222",
        "https://vss-api.eis.utoronto.ca/v2/request/change/221",
        "https://vss-api.eis.utoronto.ca/v2/request/change/220",
        "https://vss-api.eis.utoronto.ca/v2/request/change/209",
        "https://vss-api.eis.utoronto.ca/v2/request/change/208",
        "https://vss-api.eis.utoronto.ca/v2/request/change/207",
        "https://vss-api.eis.utoronto.ca/v2/request/change/206",
        "https://vss-api.eis.utoronto.ca/v2/request/change/205",
        "https://vss-api.eis.utoronto.ca/v2/request/change/204",
        "https://vss-api.eis.utoronto.ca/v2/request/change/203"
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/request/change?per_page=10&sort=created_on,desc"
        },
        "count": 10,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/request/change?sort=created_on%2Cdesc&per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/request/change?sort=created_on%2Cdesc&per_page=10&page=4",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/request/change?sort=created_on%2Cdesc&per_page=10&page=2",
            "page": 1,
            "pages": 4,
            "per_page": 10,
            "prev_url": null,
            "total": 33
        },
        "sort": "created_on,desc",
        "time": "0.01714s",
        "user": "josem"
    }
}