List
To list a summary of all your requests, do a GET request to /request resource as follows:
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
{
"_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:
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
{
"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"
}
}
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:
"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:
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
{
"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:
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
{
"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:
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
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"
{
"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:
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"
{
"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:
sort=<field_name>,<asc|desc>
The following example shows how to filter by date (latest first):
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"
{
"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"
}
}
