Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.caeither for a single or multiple deployments. 



Panel

On this page:

Table of Contents
outlinetrue


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

User Images/user/image/vmUser resource of OVF/OVA Virtual Machine images available from user's VSKEY-STOR space(tick)(tick)(tick)
ResourceURIDescriptionGETPOSTPUTPATCHOPTIONS
Images/imagePublic resource of OVF/OVA Virtual Machine
(tick)    (tick)
(tick) 


(tick)
User Images/user/image/vmUser resource of OVF/OVA Virtual Machine images available from user's VSKEY-STOR space(tick)

(tick)(tick)


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



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:

NameTypeDescription
idintUnique identifier
namestringOVA/OVF image file name
pathstringOVA/OVF image full path
created_onstringTimestamp when image was added
updated_onstringTimestamp when image was last updated

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

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


Code Block
languagepy
titleResponse Body
collapsetrue
{
    "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:

Code Block
languagepy
titleMeta key
collapsetrue
    "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"
    }


KeyDescription
first_urlContain the URLs to navigate through results.
last_url
prev_url
next_url
pageCurrent page
pagesTotal number of pages
per_pageResults per page. Maximum 100; Default 10.
totalTotal 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

example:

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


Code Block
languagepy
titleResponse Body
collapsetrue
{
    "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:

Code Blockhttp -a $TK

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


Code Block
languagepy
titleResponse Body
collapsetrue
{
    "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:

Code Block
filter=<field_name>,<operator>,<value>

Operators can be:

OperatorDescription
eqEquals
neNot equal
ltLower than
leLower equal
gtGreater than
geGreater equal
likeMatching pattern
inMatch 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:

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


Code Block
languagepy
titleResponse Body
collapsetrue
{
    "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:

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

The following example shows how to sort by path, filter by path and expand results :

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


Code Block
languagepy
titleResponse Body
collapsetrue
{
    "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:

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

NameTypeDescription
idintUnique identifier
namestringOVA/OVF image file name
pathstringOVA/OVF image full path
created_onstringTimestamp when image was added
updated_onstringTimestamp when image was last updated

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

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


Code Block
languagepy
titleResponse Body
collapsetrue
{
    "_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"
    }
}