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.

Panel

On this page:

Table of Contents

outline	true

Child pages:

Child pages (Children Display)

all	true
depth	1

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

Code Block
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

Code Block

language	py
title	Response Body
collapse	true

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

Code Block
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

Code Block

language	py
title	Response Body
collapse	true

{
    "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"
    }
}

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

Code Block

language	py
title	Meta key
collapse	true

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

Code Block

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

Code Block

language	py
title	Response Body
collapse	true

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

Code Block

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

Code Block

language	py
title	Response Body
collapse	true

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

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

Code Block

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"

Code Block

language	py
title	Response Body
collapse	true

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

Code Block

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"

Code Block

language	py
title	Response Body
collapse	true

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

Code Block
sort=<field_name>,<asc\|desc>

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

Code Block

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"

Code Block

language	py
title	Response Body
collapse	true

{
    "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"
    }
}

Versions Compared

Old Version 7

New Version Current

Key

Introduction

List

Paging

Expansion

Filtering

Sorting

Page Comparison

Versions Compared

Old Version 7

New Version Current

Key

Introduction

List

Paging

Expansion

Filtering

Sorting