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