The API is implemented in a ReST style, using the URL to specify an object and an action, HTTP GET to read state and HTTP POST to change state. In the description below, API URLs are relative to the stem https://api-jhb1.go2cloud.co.za/ where api-jhb1 refers to the availability zone for our Midrand availability zone near Midrand in South Africa.
Users, drives and servers are identified by UUIDs, which are assigned by our infrastructure and passed as a string in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
Authentication
API calls must use HTTP Basic Authentication, specifying the user’s UUID as the username and their secret API key as the password. Both are available from the user’s account profile.
Data formats
The API can be used in either text/plain(default) or application/json modes. You should specify the type of input data with an HTTP Content-Type: header, and request a type for output with an HTTP Accept: header. text/plain is the default if no headers are set.
The API sends or receives one of three types of data, according to the call:
| text/plain | application/json | |
|---|---|---|
| Single object, key value pairs of properties |
Multiple lines of text, each containing a key, followed by a space, followed by the value. e.g.: name TestServer cpu 4000 mem 2048 Data is accompanied by the HTTP header ‘X-Elastic-Output: properties’ |
JSON object. e.g.: {"name":"TestServer", "cpu":4000, "mem":2048}
|
| Multiple objects, list of values |
Multiple lines of text, each containing a space separated list of values for the same set of keys. e.g.: ip 192.168.0.1 ip 192.168.0.2 ip 192.168.0.3 Data is accompanied by the HTTP header ‘X-Elastic-Output: list’ |
JSON array of objects. e.g.: [{"type":"ip", "resource":"192.168.0.1"},
{"type":"ip", "resource":"192.168.0.2"},
{"type":"ip", "resource":"192.168.0.3"}]
|
| Multiple objects, key value pairs of properties for each |
Multiple lines of text, each containing a key, followed by a space, followed by the value. Blank lines separating objects. e.g.: name TestServer1 cpu 2000 mem 1024 name TestServer2 cpu 4000 mem 2048 Data is accompanied by the HTTP header ‘X-Elastic-Output: properties list’ |
JSON array of objects. e.g.: [{"name":"TestServer1", "cpu":2000, "mem":1024},
{"name":"TestServer2", "cpu":4000, "mem":2048}]
|
Errors
Errors are returned with an appropriate HTTP status code, an X-Elastic-Error header specifying the error type, and a text description in the HTTP body. The error types are:
| HTTP status code | X-Elastic-Error | Meaning |
|---|---|---|
| 200 OK | n/a | Command succeeded, data returned (possibly 0 length) |
| 204 No Content | n/a | Command succeeded, no data returned (by definition) |
| 400 Bad Request | usage | Invalid input data to command |
| 401 Unauthorized | auth | HTTP Basic Authentication missing or incorrect |
| 402 Payment Required | billing | Account balance and/or subscriptions do not cover command |
| 404 Not Found | missing | Command, drive, server or other object not found |
| 405 Method Not Allowed | method | GET used on command expecting POST |
| 409 Conflict | busy | Drive, server or other resource is busy |
| 500 Internal Server Error | failed | Failed command |
| 500 Internal Server Error | system | System error |
| 507 Insufficient Storage | full | Drive or other resource is full |
0 Comments