Scyld Cloud Controller Documentation
API Key Concepts
Authentication
All Scyld Cloud Services API calls require users to be authenticated with Scyld Cloud Auth. Users aquire an authentication token from Scyld Cloud Auth and then include that token, specified as the “X-Auth-Token” HTTP header, in all subsequent calls.
Additionally, all calls to Scyld Cloud Controller must include an additional HTTP header of “X-Auth-Cloudauth-Id”, specifying the User ID in Scyld Cloud Auth which was used to aquire the token. Scyld Cloud Controller verifies that the token is valid by making sure that it belongs to the given User ID, and that the token is not expired and has not been revoked. See Scyld Cloud Auth documentation for more details.
General Call Pattern
Scyld Cloud Controller API calls are issued using HTTP GET, PUT, POST, and DELETE. HTTP GET is accepted only for calls that read data, while POST is required whenever a call creates a new object. HTTP PUT manipulates (changes) objects, while DELETE destroys them.
All request GET querystring parameters should be UTF-8 and URL-encoded.
PUT and POST parameters are expected in JSON format.
All requests can include a version indicator as the first segment of the URI, if a particular version is needed. If the version segment is not present, the current version is assumed. The version segment begins with a lowercase ‘v’ as shown below.
Every attempt will be made to provide an API interface that remains backwards-compatible but if we do change an API method’s interface, we will increment the API version number. We will also continue to support the older version until its no longer reasonable and/or feasible to do so. If additions are made to the API that do not change the behavior of any other methods, the version number may not be incremented.
The version segment should be formatted as follows:
/v1.0/user - Request explicit API version (1.0) of this method. /user - Request without explicit version; assumes current API version.
All responses are in JSON format. See http://www.json.org for details about JSON and references to client libraries.
Nominal Responses
All responses returned with an HTTP 200 status code are returned with the following parameters:
- success - Boolean. Success indicator.
- version - String. API version handling this request.
- data - Varies, depending on specific method called. This is usually the interesting part.
Additionally, The following optional parameters may be returned:
- message - String. General informational message.
- error - String. Used when success == False. Informational message about the error condition this request encountered.
Error Responses
All responses returned with an HTTP 400-series status code are returned with the following parameters:
- msg - String. Informational message about what caused the error.
HTTP Status Codes
The following is a list of status codes used by Scyld Cloud Controller.
200 OK
No critical errors encountered. It is still important to check the value of the “success” parameter in the response body, however, as the API can return 200 OK, but still have success=False.
400 Bad Request
This is generally caused by malformed input parameters or request method.
401 Unuthorized
Unabled to validate your auth token with Scyld Cloud Auth.
403 Forbidden
User is authenticated but access to the resource or operation requested is denied.
404 Not Found
Usually refers to an incorrect path to the API method. Also indicates that the primary object in the request does not exist.
407 Proxy Authentication Required
The X-Auth-Token is missing. Please aquire one from Scyld Cloud Auth and provide to Scyld Cloud Controller.
409 Conflict
The object you are trying to create already exists.
500 Internal Server Error
An internal failure occured within Scyld Cloud Controller and your request was unable to be processed. Possibly caused by a service or network outage; either try again later or contact support.
504 Gateway Timeout
Scyld Cloud Controller was unable to communicate with Scyld Cloud Auth. Without this authentication piece, Scyld Cloud Controller is unable to process requests.