Introduction

Deploying virtual machine from OVA or OVF images has been one of the core features of the RESTful API. Now, you are able to upload any Open Virtualization Format archives in your personal space at 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://vskeysvskey-torstor.eis.utoronto.ca and use it to deploy one or many virtual machines. It is also possible to export an existent virtual machine (Virtual Machine - Attributes) to OVF and then use this OVF to deploy new ones, either for a single or multiple deployments.

Panel

On this page:

Table of Contents

outline	true

The following table shows a brief description and 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

http OPTIONS "

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

Note

title	OPTIONS HTTP method

Remember, you can also show what methods are allowed and description, parameters, etc. by making an OPTIONS HTTP request to /v2/image.

Code Block

language	bash

Code Block
curl -X POST https://vss-api.eis.utoronto.ca:8001/v2/image" auth/request-token -u <username>

For example, extracting the token with the jq command:

Code Block
TK=$(curl -X OPTIONSPOST "https://vss-api.eis.utoronto.ca:8001/v2/image"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 ISO 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

Personal space path

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:

Code Block
http -a $TK GET "https://vss-api.eis.utoronto.ca:8001/v2/image" "Authorization: Bearer $TK" curl -uH "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca:8001/v2/image"

Code Block

language	py
title	Response Body
collapse	true

{
    "data": [
        "https://vss-api.eis.utoronto.ca/v2/image/31",
        "_links": {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:8001/v2/",
        "/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

language	py
title	Meta key
collapse	true

    "meta": {
        "_link": {
            "self": "https://vss-api.eis.utoronto.ca:8001/v2/image"
    },
    /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:

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

language	py
title	Response Body
collapse	true

{
    "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": {
            "nameself": "1605T-sick_stallman"https://vss-api.eis.utoronto.ca/v2/image?per_page=5"
        },
        "count": 5,
        "pages": {
    "path        "first_url": "50124dc2-aba4-5c57-130c-da207557e5bd/1605T-sick_stallman.ovf"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 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

language	py
title	Response Body
collapse	true

{
    "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",
            "namelast_url": "photon-custom-1.0-37d64ad-RC1https://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:

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:

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

Code Block

language	py
title	Response Body
collapse	true

{
    "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 "photon-custom-1.0-37d64ad-RC1.ovaEST"
        }
    ],
    "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
curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/image?filter=name,like,ubu%&expand=1&sort=path,asc"

Code Block

language	py
title	Response Body
collapse	true

{
    "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": "photon-custom-1.0-a6f0f63-RC
        },
        {
            "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,
  "photon-custom-1.0-a6f0f63-RC.ova"
          "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,
            ": 5per_page": 10,
            "prev_url": null,
            "total": 4
        },
        "sort": "path,asc",
        "time": "0.25403s00476s",
        "user": "jmjosem"
    }
}

Note

The attribute value you will use to deploy new virtual machines using an image is path.

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:

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:

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

language	py
title	Response Body
collapse	true

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

Versions Compared

Old Version 4

New Version Current

Key

Introduction

List

Paging

Expansion

Filtering

Sorting

User

List

Page Comparison

Versions Compared

Old Version 4

New Version Current

Key

Introduction

List

Paging

Expansion

Filtering

Sorting

User

List