Introduction

The API has introduced a process to deploy OVA or OVF from either our public repository or an Open Virtualization Format file provided by a user and uploaded to https://vskey-stor.eis.utoronto.ca, either for a single or multiple deployments.

On this page:

The following table summarizes the HTTP methods allowed to interact with Open Virtualization Format images either for public use or personal use:

Resource	URI	Description	GET	POST	PUT	PATCH	OPTIONS
Images	/image	Public resource of OVF/OVA Virtual Machine
User Images	/user/image/vm	User resource of OVF/OVA Virtual Machine images available from user's VSKEY-STOR space

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

Public

The public repository holds an OVA catalog of common linux distributions such as Ubuntu, VMware PhotonOS and CoreOS optimized for cloud deployment.

List

In order to list available OVA/OVF images you should make a GET request to the endpoint /v2/image passing your access token. As a result, you will get list of images available in the public repository in form of JSON objects with the following attributes:

Name	Type	Description
id	int	Unique identifier
name	string	OVA/OVF image file name
path	string	OVA/OVF image full path
created_on	string	Timestamp when image was added
updated_on	string	Timestamp when image was last updated

The following examples implements HTTPie and CURL to list available OVA/OVF images:

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

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

Response Body

{
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/image/31",
        "https://vss-api.eis.utoronto.ca/v2/image/29",
        "https://vss-api.eis.utoronto.ca/v2/image/35",
        "https://vss-api.eis.utoronto.ca/v2/image/36",
        "https://vss-api.eis.utoronto.ca/v2/image/24",
        "https://vss-api.eis.utoronto.ca/v2/image/33",
        "https://vss-api.eis.utoronto.ca/v2/image/34",
        "https://vss-api.eis.utoronto.ca/v2/image/25",
        "https://vss-api.eis.utoronto.ca/v2/image/26",
        "https://vss-api.eis.utoronto.ca/v2/image/27"
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/image"
        },
        "count": 10,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=10&page=2",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=10&page=2",
            "page": 1,
            "pages": 2,
            "per_page": 10,
            "prev_url": null,
            "total": 14
        },
        "time": "0.00854s",
        "user": "josem"
    }
}

Paging

All requests to the /image 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/image"
        },
        "count": 10,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=10&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=10&page=2",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=10&page=2",
            "page": 1,
            "pages": 2,
            "per_page": 10,
            "prev_url": null,
            "total": 14
        },
        "time": "0.00854s",
        "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/image?per_page=5" "Authorization: Bearer $TK"

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

Response Body

{
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/image/31",
        "https://vss-api.eis.utoronto.ca/v2/image/29",
        "https://vss-api.eis.utoronto.ca/v2/image/35",
        "https://vss-api.eis.utoronto.ca/v2/image/36",
        "https://vss-api.eis.utoronto.ca/v2/image/24"
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/image?per_page=5"
        },
        "count": 5,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=5&page=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=5&page=3",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=5&page=2",
            "page": 1,
            "pages": 3,
            "per_page": 5,
            "prev_url": null,
            "total": 14
        },
        "time": "0.00815s",
        "user": "josem"
    }
}

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

Expansion

Image 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/image?per_page=1&page=5&expand=1" "Authorization: Bearer $TK"

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

Response Body

{
    "data": [
        {
            "created_on": "2017-11-24 Fri 15:37:36 EST",
            "data_store": "vss-ISOs",
            "folder": "VmImages/core-os",
            "id": 24,
            "label": "VmImages/core-os/coreos_production_vmware_ova.ova",
            "name": "coreos_production_vmware_ova.ova",
            "path": "[vss-ISOs] VmImages/core-os/coreos_production_vmware_ova.ova",
            "public": true,
            "updated_on": "2018-02-09 Fri 11:37:05 EST"
        }
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/image?per_page=1&page=5&expand=1"
        },
        "count": 1,
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=1&page=1&expand=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=1&page=14&expand=1",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=1&page=6&expand=1",
            "page": 5,
            "pages": 14,
            "per_page": 1,
            "prev_url": "https://vss-api.eis.utoronto.ca/v2/image?per_page=1&page=4&expand=1",
            "total": 14
        },
        "time": "0.01007s",
        "user": "josem"
    }
}

Filtering

VM Images 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 object has, for instance /image can be filtered by attribute. Thus, the following example will filter Ubuntu images:

curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/image?filter=name,like,ubu%&expand=1&per_page=1"

Response Body

{
    "data": [
        {
            "created_on": "2017-11-24 Fri 15:37:36 EST",
            "data_store": "vss-ISOs",
            "folder": "VmImages/ubuntu",
            "id": 25,
            "label": "VmImages/ubuntu/ubuntu-zesty-server-cloudimg-i386.ova",
            "name": "ubuntu-zesty-server-cloudimg-i386.ova",
            "path": "[vss-ISOs] VmImages/ubuntu/ubuntu-zesty-server-cloudimg-i386.ova",
            "public": true,
            "updated_on": "2018-02-09 Fri 11:37:06 EST"
        }
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/image?filter=name,like,ubu%&expand=1&per_page=1"
        },
        "count": 1,
        "filter": "name,like,ubu%",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/image?filter=name%2Clike%2Cubu%25&per_page=1&page=1&expand=1",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/image?filter=name%2Clike%2Cubu%25&per_page=1&page=4&expand=1",
            "next_url": "https://vss-api.eis.utoronto.ca/v2/image?filter=name%2Clike%2Cubu%25&per_page=1&page=2&expand=1",
            "page": 1,
            "pages": 4,
            "per_page": 1,
            "prev_url": null,
            "total": 4
        },
        "time": "0.07245s",
        "user": "josem"
    }
}

Sorting

Images 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 sort by path, filter by path and expand results :

curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/image?filter=name,like,ubu%&expand=1&sort=path,asc"

Response Body

{
    "data": [
        {
            "created_on": "2017-11-24 Fri 15:37:36 EST",
            "data_store": "vss-ISOs",
            "folder": "VmImages/ubuntu",
            "id": 26,
            "label": "VmImages/ubuntu/ubuntu-xenial-server-cloudimg-amd64.ova",
            "name": "ubuntu-xenial-server-cloudimg-amd64.ova",
            "path": "[vss-ISOs] VmImages/ubuntu/ubuntu-xenial-server-cloudimg-amd64.ova",
            "public": true,
            "updated_on": "2018-02-09 Fri 11:37:06 EST"
        },
        {
            "created_on": "2017-11-24 Fri 15:37:36 EST",
            "data_store": "vss-ISOs",
            "folder": "VmImages/ubuntu",
            "id": 28,
            "label": "VmImages/ubuntu/ubuntu-xenial-server-cloudimg-i386.ova",
            "name": "ubuntu-xenial-server-cloudimg-i386.ova",
            "path": "[vss-ISOs] VmImages/ubuntu/ubuntu-xenial-server-cloudimg-i386.ova",
            "public": true,
            "updated_on": "2018-02-09 Fri 11:37:06 EST"
        },
        {
            "created_on": "2017-11-24 Fri 15:37:36 EST",
            "data_store": "vss-ISOs",
            "folder": "VmImages/ubuntu",
            "id": 27,
            "label": "VmImages/ubuntu/ubuntu-zesty-server-cloudimg-amd64.ova",
            "name": "ubuntu-zesty-server-cloudimg-amd64.ova",
            "path": "[vss-ISOs] VmImages/ubuntu/ubuntu-zesty-server-cloudimg-amd64.ova",
            "public": true,
            "updated_on": "2018-02-09 Fri 11:37:06 EST"
        },
        {
            "created_on": "2017-11-24 Fri 15:37:36 EST",
            "data_store": "vss-ISOs",
            "folder": "VmImages/ubuntu",
            "id": 25,
            "label": "VmImages/ubuntu/ubuntu-zesty-server-cloudimg-i386.ova",
            "name": "ubuntu-zesty-server-cloudimg-i386.ova",
            "path": "[vss-ISOs] VmImages/ubuntu/ubuntu-zesty-server-cloudimg-i386.ova",
            "public": true,
            "updated_on": "2018-02-09 Fri 11:37:06 EST"
        }
    ],
    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca/v2/image?filter=name,like,ubu%&expand=1&sort=path,asc"
        },
        "count": 4,
        "filter": "name,like,ubu%",
        "pages": {
            "first_url": "https://vss-api.eis.utoronto.ca/v2/image?sort=path%2Casc&filter=name%2Clike%2Cubu%25&page=1&expand=1&per_page=10",
            "last_url": "https://vss-api.eis.utoronto.ca/v2/image?sort=path%2Casc&filter=name%2Clike%2Cubu%25&page=1&expand=1&per_page=10",
            "next_url": null,
            "page": 1,
            "pages": 1,
            "per_page": 10,
            "prev_url": null,
            "total": 4
        },
        "sort": "path,asc",
        "time": "0.00476s",
        "user": "josem"
    }
}

User

Before listing your images, you should Synchronize your repository image files with the API but first you must've uploaded an OVF with its related VMDK files or an OVA package to https://vskey-stor.eis.utoronto.ca . To sync your files, make a PATCH request to /v2/user/image/vm as follows:

http PATCH "https://vss-api.eis.utoronto.ca/v2/user/image/vm" "Authorization: Bearer $TK"

curl -H "Authorization: Bearer $TK" -X PATCH "https://vss-api.eis.utoronto.ca/v2/user/image/vm"

The previous request will submit an image sync request which you can follow up by requesting checking the following resource and replacing <id> with the returned request id /v2/request/image_sync/<id> or you can wait for the email confirmation.

List

In order to list your OVA/OVF images you should make a GET request to the endpoint /v2/user/image/vm passing your access token. As a result, you will get list of images available in your VSKEY-STOR space in form of JSON objects with the following attributes:

Name	Type	Description
id	int	Unique identifier
name	string	OVA/OVF image file name
path	string	OVA/OVF image full path
created_on	string	Timestamp when image was added
updated_on	string	Timestamp when image was last updated

The following examples implements HTTPie and CURL to list available OVA/OVF images:

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

Response Body

{
    "_links": {
        "image": "https://vss-api.eis.utoronto.ca/v2/user/image",
        "self": "https://vss-api.eis.utoronto.ca/v2/user/image/vm"
    },
    "data": [
        {
            "created_on": "2017-11-17 Fri 13:51:41 EST",
            "data_store": "vssUser-xfers",
            "folder": null,
            "id": 2,
            "label": "xenial-server-cloudimg-amd64.ova",
            "name": "xenial-server-cloudimg-amd64.ova",
            "path": "[vssUser-xfers] josem/images/xenial-server-cloudimg-amd64.ova",
            "public": false,
            "updated_on": "2017-11-17 Fri 13:51:41 EST"
        },
        {
            "created_on": "2017-11-17 Fri 13:51:41 EST",
            "data_store": "vssUser-xfers",
            "folder": null,
            "id": 3,
            "label": "graylog-2.1.2-1.ova",
            "name": "graylog-2.1.2-1.ova",
            "path": "[vssUser-xfers] josem/images/graylog-2.1.2-1.ova",
            "public": false,
            "updated_on": "2017-11-17 Fri 13:51:41 EST"
        }
    ],
    "meta": {
        "count": 19,
        "time": "0.00536s",
        "user": "josem"
    }
}

Browser not supported