Using the REST API

The REST API request message includes parameters in the resource URL; responses are in JSON format.

All request messages must include a unique user id (assigned by Cloudshare), a timestamp and a signature calculated using the user’s unique API key (also assigned by Cloudshare).

General Request URL Format

GET https://use.cloudshare.com/API/<ver>/<resource>?UserApiId=<id>&timestamp=<time>&HMAC=<signature>&param1=<p1>&param2=<p2>....

Parameters

ver API version. Currently v2
resource Specific API resource name.
UserApiId Unique user id (assigned by Cloudshare). This parameter must be included in every request.
token Unique and random string of ten characters (a-z, A-Z, 0-9).
timestamp Time, in seconds, from Jan 1, 1970 0:00:00 UTC. This parameter must be included in every request.
Example: Oct 1, 2012 7:00 GMT is 1349074800
signature HMAC signature (see below). This parameter must be included in every request. A sample calculation is shown below.
param
optional		 Specific parameters for each request. Some are optional.

Authentication

The application user is assigned a userapiid, which is used to identify it in each request. The user also has a private API key, which is used to calculate a message signature.

Signature

The signature is an SHA1 hash of a string composed of the following components:

  1. start with the APIKey value
  2. append to this the resource name, in lower case letters (e.g. resource ListEnvironments would be listenvironments)
  3. sort all the request parameters, including timestamp,token and UserApiId, converted to lower case and with their values (in original case), without equals sign, in ascending order and append this
  4. calculate the SHA1 hash of the above string with the APIKey:
    1. e.g.: for the resource ListEnvironments, and parameters Param1=Alice, P2=Bob, timestamp=123456, alpha=beta, UserApiId=AAAABBBBCCCCDDDD and token=A1b2C3d4E5 and APIKey=XXXXX, the hash calculation will be: SHA1(XXXXXlistenvironmentsalphabetap2Bobparam1Alicetimestamp123456tokenA1b2C3d4E5userapiidAAAABBBBCCCCDDDD)
  5. convert the result to lowercase hexadecimal value and use this as the HMAC signature.

Timestamp

The timestamp value will be valid for sixty seconds.

Name and String parameters

Names and other string-type parameters containing spaces should encode the spaces as %20.
For example, the string “A linux machine” would be represented as A%20linux%20machine in the https request.

JSON response block

{
   "data": {
[Request specific response data.]
},
   "remaining_api_calls": 968, 
    "status_additional_data": null, 
    "status_code": "0x20000", 
    "status_text": "Success"
}

HTTP Response Status

All requests will receive an HTTP response status code. If the request was successful, the code will be 200 (OK). If there is a problem, one of the codes listed below will be returned. In addition, some requests will return more details in the body of the JSON response message.

Response Status HTTP Status Response message details
OK 200 {“status_code”: “0x20000”,
“status_text”: “Success”}
Bad token
The UserApiId token is invalid		 400 {“data”:null,”remaining_api_calls”:100000,
“status_code”:”0x40401″,
“status_text”:”User not found”,
“status_additional_data”:null}
Permission denied
The user does not have permission to run this request (e.g., ProPlus user attempting an Enterprise user action)		 403 {“status_additional_data”: null,
“status_code”: “0x40301”,
“status_text”: “Permission denied”}
Bad URL
The URL is badly formed and the request not recognized.		 404 ‘The resource cannot be found’
Invalid Action
There was an error processing the request		 500 {“status_code”: “0x50001”,
“status_text”: “Action failed”}
Bad Timestamp
The timestamp value is invalid		 500 {“message”:”Timestamp skew: The request timestamp is skewed by more then 1 minute”,
“additional_info”:null}
Bad Signature
The signature is invalid		 500 {“status_additional_data”: “HMAC doesn’t match data signed data, your HMAC should start with ac5…”,
“status_code”: “0x50017”,
“status_text”: “HMAC doesn’t match data signed data”}