Using the REST API

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

All request messages must include the user’s unique UserApiId (a token 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_t>&HMAC=<signature>&param1=><p1>&param2=<p2>....

Parameters

ver API version. Currently v1
resource Specific API resource name.
userApiId Unique user id (assigned by Cloudshare). This parameter must be included in every request.
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.
Param
optional		 Specific parameters for each request. These are optional.

Authentication

The application user is assigned a UserApiId, which is used to identify him in each request. User also has private API key, which is used to calculate a message signature (SHA).

Signature

The signature is an SHA1 hash of all the parameters in the request message, calculated as follows:

  1. sort all parameters including timestamp and UserApiId in case insensitive  ascending  order;
  2. calculate SHA1 hash of the parameter names in lowercase, and their corresponding values (without equals sign) in the order above, with the APIIdKey:
    1. e.g.: for the parameters Param1=Alice, P2=Bob, timestamp=123456, alpha=beta, UserApiId=AAAABBBBCCCCDDDD, UserAPIKey=QQQQRRRRSSSSTTTT the hash calculation will be: SHA1(QQQQRRRRSSSSTTTTalphabetap2Bobparam1Alicetimestamp123456userapiidAAAABBBBCCCCDDDD, API Key)
  3. convert the result to lowercase hexadecimal value, this will be the value of the HMAC signature parameter.

note: if you are using Powershell – use System.Security.Cryptography.SHA1Managed in order to compute hash

Timestamp

The timestamp value will be valid for sixty seconds.

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 Request was successfully completed.
Invalid Action
There was an error processing the request		 500 “message”: “InternalServerError”
Forbidden Request
The user does not have permission to run this request (e.g., Pro user attempting an Enterprise user action)		 400 “message”: “Forbidden”
Bad URL
The URL is badly formed and the request not recognized.		 404 ‘The resource cannot be found’
Bad token
The UserApiId token is invalid		 400 “message”: “NotFound”
Bad Timestamp
The timestamp value is invalid		 500 {“timestamp”:1353924562,
“message”:”An error has occurred processing your request, please contact support@cloudshare.com”}
Bad Signature
The signature is invalid		 500 {“timestamp”:1353924562,
“message”:”An error has occurred processing your request, please contact support@cloudshare.com”}