Using the REST API

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...
...
  1. Unlike API v2, various requests use different HTTP verbs such as GET, POST, PUT, and DELETE.
  2. All requests should have the Accept: application/json header
  3. PUT and POST requests that have payload should have the Content-Type: application/json, and Content-Length headers.
  4. 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:

  1. 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.
  2. The entire request URL (e.g. https://use.cloudshare.com/api/v3/envs/action/suspend?envId=ENXYZ123)
  3. The same timestamp value given in the Authorization header
  4. 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.

Bash example

#!/bin/bash
# This script is a CloudShare API call example
# Get the API ID and the KEY from your user details page
# Replace the following two parameters
API_ID="<ID>"
API_KEY="<KEY>"

URL="https://use.cloudshare.com/api/v3/envs"

TIMESTAMP=$(date +%s)
TOKEN=$(tr -dc A-Za-z0-9 </dev/urandom | head -c 10 ; echo '')
HMAC=$(echo -n $API_KEY$URL$TIMESTAMP$TOKEN | sha1sum|awk '{print $1}')
AUTH_PARAM="userapiid:$API_ID;timestamp:$TIMESTAMP;token:$TOKEN;hmac:$HMAC"

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: cs_sha1 $AUTH_PARAM" -X GET $URL