The ITS Private Cloud API allows you to manage Virtual Machines and resources hosted in the EIS virtual cloud in a simple, programatic manner using HTTP requests. The endpoints are intuitive, self descriptive and powerful, allowing you to make calls to retrieve information such as object properties, performance metrics or even to execute actions.

We have wrapped the official vSphere API with all features you are familiar with through this API, so it can be easily be used from scripts on any given situation.

HTTP Requests

Since the ITS Private Cloud API is compliant with the RESTful principles, the following HTTP verbs have been implemented to develop actions through the API.

Method	Description

Method	Description
GET	For simple retrieval of information about your user account, Virtual Machines, Templates, Fault Domains, Snapshots and many other resources you should use the GET method. The information you request will be returned to you as a JSON object.
POST	To create or deploy a new Virtual Machine, Folder, Snapshot, you should use the POST method.
PUT	This method should be used to update the information about a resource, such as a Virtual Machine.
DELETE	To decommission a resource and remove it from your account, the DELETE method should be used. This will remove the specified object if it is found and you have the right permission, otherwise you will get the right response in such case.
OPTIONS	Resource documentation is available for every resource in JSON representation.

HTTP Responses

Every response given by the API is compliant with the HTTP Response status, meaning that if you get a 200 status code, the request has been successful, along with a response body as a JSON object. Most of the Virtual Machine update and creation resources return a 202 status, which means your request has been accepted for processing and has been put into the queue. In this particular case, the response body comes with a URI to check the status of the requested task.

HTTP/1.0 401 UNAUTHORIZED
... headers ...
Location: https://vss-api.eis.utoronto.ca/auth/request-token

{
    "error": "unauthorized", 
    "message": "Please authenticate with your token.", 
    "status": 401
}

Inside of this JSON object, there are three main keys which in all successful request will be present: _links, data, meta. The first element _links contain Hypermedia Control for the resource, this includes self and the next upper resource. data contains all requested elements which could be more JSON objects or arrays including JSON objects. Lastly, meta stores the user who requested the resource, how many elements were returned and how much time took to complete the request in question.

JSON Response

HTTP/1.0 200 OK
... headers ...
{
    "_links": {
        "api": "https://vss-api.eis.utoronto.ca/v2", 
        "self": "https://vss-api.eis.utoronto.ca/v2/version"
    }, 
    "data": {
        "version": "DEV-v2"
    }, 
    "meta": {
        "count": 1,
        "time": "0.00047s", 
        "user": "jm"
    }
}

Rate Limit

The number of requests that can be made to the API is currently limited to 5,000 per hour per user. The rate limiting information is shown within the response headers of each request

Response Header	Description

Response Header	Description
X-RateLimit-Limit	The number of requests that can be made per time period.
X-RateLimit-Remaining	The number of requests remaining before you reach your request limit.
X-RateLimit-Reset	Represented by the Unix Epoch time it represents the time when the oldest request will expire.

Keep in mind that having RateLimit-Remaining count is above zero, is more than enough to make additional requests.

Rate Limit Headers

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 2999
X-RateLimit-Reset: 1462154400

Too many requests response

Security and Authentication

For security reasons, the API is not publicly available, thus in order to access it you should have the VSS-VPN installed, configured and , then you would be able to reach it by vss-api.eis.utoronto.ca.

The API requires a token sent on each request via the Authorization header to authenticate. This token can be got by making a POST request to the URI /auth/request-token where you'll include your VSKEY credentials using the Authorization Header.

Cross Origin Resource Sharing

In order to make requests to the API from other domains, the ITS Private Cloud API support Cross Origin Resource Sharing (CORS). A prefilght request should be sent prior utilizing any resource in the API to dynamically allow valid domains to make AJAX calls, this by using the OPTIONS method along with the Origin request header with the value of the domain to be permitted. A response will be madewith its maximum validity time, methods allowed, headers and credentials as explained below:

Response Header	Description

Response Header	Description
Access-Control-Allow-Credentials	Allows to send your token for authentication.
Access-Control-Allow-Headers	Contain the headers available to requests from the origin domain.
Access-Control-Allow-Methods	Allowed methods by domain.
Access-Control-Allow-Origin	Domain sent by the client or browser as the origin of the request via the Origin header. Domain must be part of the main utoronto.ca
Access-Control-Max-Age	Length of time that the access is considered valid. After this expires, a new preflight should be sent.

Preflight Request

Resources

The ITS Private Cloud API provides the URLs for the appropriate RESTful HTTP operations as displayed in the following table.

Base URI is https://cloud-api.eis.utoronto.ca/v2

Resource	URI	Description	GET	POST	PUT	DELETE

Resource	URI	Description
Authentication	/auth/request-token	Authentication Resource to generate access token
Virtual Machine	/vm	Virtual Machine management resource. Create, list, update and delete virtual machines.
Folder	/folder	Folder Management resource. List, update and create logical folders.
Network	/network	Network Management resource. List permitted networks.
Content Library	/contentlib	Content Libraries and items.
Image	/image	OVF/OVA Virtual Machine images available from VSKEY-STOR.
Virtual Machine Template	/template	Virtual Machine Template management resource. List available VM templates.
ISOs	/iso	CD/DVD iso images available to customers.
Floppy	/floppy	Floppy images available to customers.
Fault Domains	/domain	Fault Domain resource. List of available fault domains.
Operating Systems	/os	Virtual Machine supported operating systems resource.
Inventory	/inventory	Inventory requests. Submit an inventory of your VMs.
Request	/request	Request Management resource. List New VM requests, change, snapshot, inventory, folder requests.
User	/user	User information resource. Read current user information from vCenter, RESTful WS and VSKEY5.
Session	/session	Current user active sessions in vCenter.
Status	/status	Service status resource.
VSS	/vss	VSS related resource providing default settings, VSS Service and Service Group Resources
VSS Service	/vss/service /vss/service-group	List existing ITS System Status Page components and component group..
Ping	/ping	Troubleshooting endpoint

Introduction