Developer API

  1. Functionality
  2. Versioning
  3. API Token
  4. Rate limiting
  5. Pagination
  6. CRUD: Create, Retrieve, Update and Destroy

Functionality

The access to the API must be done from the domain https://api.cloudwalk.io/{version}.

The requests should be made using the HTTPS protocol.

All date and time records are returned in ISO 8601 standard:

YYYY-MM-DDTHH:MM:SSZ

Versioning

When using the CloudWalk API, it is necessary to provide the version being used. Currently only the version v1 is available for use, but eventually new versions will become available.

Example of URL: https://api.cloudwalk.io/v1/devices

API Token

All operations available on the API interface should always use a valid API token. The API token management is done directly on the CloudWalk Manager, by simply accessing the top menu My account, and then the option API.

API Token

Example of URL:

https://api.cloudwalk.io/{version}/devices?access_token=6eb718f846c6d303ed8054cdf7ccdb18c821de18

Rate limiting

By default, an IP address is allowed to perform up to 3,600 requests per hour. The rate limit status can be checked on the HTTP headers of any API request:

$ curl -i https://api.cloudwalk.io/v1/devices?access_token=$TOKEN

HTTP/1.1 200 OK
Date: Wed, 28 Jan 2015 18:40:50 GMT
X-Rate-Limit-Limit: 3600
X-Rate-Limit-Remaining: 3599
X-Rate-Limit-Reset: 1422474051

CRUD: Create, Retrieve, Update and Destroy

To perform an operation on a resource (app, logical number, group, etc), a HTTP request is made to the URL using the appropriate HTTP verb.

The four HTTP verbs used in CRUD operations are:

  1. GET: Finds a specific resource or collection of resources from an URL. For example, GET /{version}/devices returns a list with all serial numbers, while a GET /{version}/devices/135 returns only the serial number with the ID 135.
  2. POST: Creates a new resource. For example, POST /{version}/devices creates a new serial number. The information sent in the POST request would then be used to fill the properties of the serial number.
  3. PUT: Updates an existing resource. For example, PUT /{version}/devices/135 updates the serial number with the ID 135. The information sent in the PUT request would then be used to update the properties of the serial number.
  4. DELETE: Deletes an existing resource. For example, DELETE /{version}/devices/135 deletes the serial number with the ID 135.

Pagination

Requests that return multiple records are paginated, where the default pagination size is 30 records. The sub-sequent pages are defined by the parameter &page, which starts on 1. The default amount of returned records can be changed by defining the parameter &per_page, up to 100 records.

https://api.cloudwalk.io/v1/devices?access_token=$TOKEN&page=1&per_page=50
https://api.cloudwalk.io/v1/devices?access_token=$TOKEN&page=2&per_page=50