The following document describes the common REST interface to the CloudShare API v3. It describes how to authenticate, call requests, and receive responses.
CloudShare API v3 SDKs
We recommend using our open source SDKs available at GitHub:
They implement a convenient interface that handles the authentication for you.
The Request
All REST API calls are standard HTTP 1.1 requests such as:
GET /api/v3/envs HTTP/1.1 Host: use.cloudshare.com Connection: keep-alive Accept: application/json Referer: http://localhost:8081/driver/ User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36... ...
-
Unlike API v2, various requests use different HTTP verbs such as
GET
,POST
,PUT
, andDELETE
. -
All requests should have the
Accept: application/json
header -
PUT and POST requests that have payload should have the
Content-Type: application/json
, andContent-Length
headers. - Request parameters are passed using the query string, the request payload in the form of a JSON object, or as part of the URL. You should refer to each request documentation for details.
The Authorization Request Header
The above request will fail without the Authorization
header. CloudShare authentication protocol is based on OAuth 1, and requires the Authorization
request header for each request in the following format:
GET /api/v3/envs HTTP/1.1 Host: use.cloudshare.com Authorization: cs_sha1 <auth_param> ...
Where <auth_param>
is an ordered, semi-colon-separated list of key-value pairs of the following values:
userapiid |
A valid user API ID. Available at the user’s details page. If the API ID field is blank, click on the “Generate API Credentials” button to receive your API ID and Key pair. |
timestamp |
The request time, in seconds, since Jan 1, 1970 0:00:00 UTC. For example: Oct 1, 2012 7:00 GMT is 1349074800. From the time the entire request is formed, it is valid for 60 seconds. |
token |
A per request unique token of exactly 10 random alphanumeric characters (a-z, A-Z, 0-9). Authenticated requests are not allowed to be called more than once. |
hmac |
HMAC signature. The request is signed with the user’s API Key. A sample calculation is shown below. |
For example:
userapiid:5VLLDABQSBESQSKY;timestamp:1424606753;token:5686464440;hmac:842bba7f7382d91b9d1185becd1a2d7ac9f2263c
The HMAC Signature
The HMAC is a SHA1 digest of the concatenated string values of:
- A valid user API Key, corresponding to the API ID given in the Authorization header. Also available at the user’s details page. If the API Key field is blank, click on the “Generate API Credentials” button to receive your API ID and Key pair.
- The entire request URL (e.g.
https://use.cloudshare.com/api/v3/envs/action/suspend?envId=ENXYZ123
) - The same
timestamp
value given in the Authorization header - The same
token
value given in the Authorization header
For example:
4P3RuSCfFbLQvqJqrBWWrxcxIjZHdlz1CkFqQR4jkIftn3C6wTGfcTawQNMKshUohttps://use.cloudshare.com/api/v3/envs/action/suspend?envId=ENXYZ12314246067535686464440
Each SHA1 byte is converted to a 2 digit hex value and concatenated into one string. For example, the above string comes out as:
f10797fe7526cb3367a40268cd7fb654f152ec29
Response
The REST API responses are standard HTTP 1.1 responses:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Access-Control-Allow-Origin: * Access-Control-Allow-Headers: Authorization,Content-Type Access-Control-Allow-Methods: POST,GET,PUT,DELETE,OPTIONS Date: Sun, 22 Feb 2015 12:30:55 GMT Content-Length: 45 ...
Success Response
On empty success (HTTP status code 204) the response is empty.
On success (any other 2xx HTTP status code) the response is a JSON value: object, array, string, number, or boolean.
Error Response
On errors (HTTP status code 4xx or 5xx), the response is a JSON object like so:
{ "message": "User not found", "code": "0x40401" }
The message
parameter is a human readable message.
The code
parameter is a hexadecimal number. Its 3 most significant digits are the HTTP status code, and the rest of the number is a CloudShare specific enumeration.