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>×tamp=<time>&HMAC=<signature>¶m1=<p1>¶m2=<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:
- start with the APIKey value
- append to this the resource name, in lower case letters (e.g. resource ListEnvironments would be listenvironments)
- 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
- calculate the SHA1 hash of the above string with the APIKey:
- 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)
- 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”} |