Overview

Requests

Authentication

All requests other than tiles must use basic authentication. Please contact WDT for a username and password (also referred to as an application ID and key). Up to five passwords may be in use at any time. This allows old passwords to be disabled without any downtime.

Methods

All requests use HTTP GET. HTTPS is recommended, but not required.

Parameters

Some requests may have parameters in the URI query string. Details are provided in the endpoint descriptions.

Unless specified otherwise, timestamps use UTC and are represented as ISO8601 strings (i.e., YYYY-MM-DDThh:mm:ssZ). Resource identifiers use UUIDs and are represented as strings in 8-4-4-4-12 format.

Headers

All requests other than tiles must include a basic authentication header.

Requests may use an Accept-Encoding header to obtain gzip-encoded JSON:

Accept-Encoding: gzip

Identifers

Every resource is identified by a UUID. For convenience in certain cases, a human-friendly name may also identify a resource. The use of IDs should be preferred, though, to avoid ambiguity.

Examples

Endpoint descriptions provide cURL examples to facilitate experimentation. Examples use the -n option to fetch credentials from a ~/.netrc file, which should include an entry similar to the following:

machine skywise-tiles.api.wdtinc.com
  login {username}
  password {token}

Rate Limits

To protect against abuse and buggy code, the API limits the number of requests each user can make within a certain time interval. More details are coming soon.

CORS

The API supports cross-origin resource sharing, so that browsers can make requests using JavaScript served from any domain.


Responses

Status Codes

The result of an API request can be identified by the status code returned.

Status Description
200 OK the request succeeded
201 Created the resource was successfully created (such as a new style)
400 Bad Request the request body is syntactically invalid
401 Unauthorized the authentication credentials are invalid, expired, or missing
403 Forbidden the authentication credentials do not provide access to specified resource
404 Not Found the specified resource does not exist
422 Unprocessable Entity one or more request parameters are invalid
429 Too Many Requests the request has been rate-limited (retry later)
500 Internal Server Error something is wrong on the server (contact support if the issue persists)
503 Service Unavailable the API is unavailable (contact support if the issue persists)

Client error responses (codes 400-499) also have a JSON body that provides details about the cause of the error.

Formats

All requests other than tiles return minified JSON. Futher details and examples (pretty-printed for readability) are provided in the endpoint descriptions.

Gzip-encoding of JSON responses is supported and recommended (see headers).

Unless specified otherwise, timestamps use UTC and are represented as ISO8601 strings (i.e., YYYY-MM-DDThh:mm:ssZ). Resource identifiers use UUIDs and are represented as strings in 8-4-4-4-12 format.


Versioning

Version 1 is the current and only supported major version of the API.

Every request must specify a supported major API version in the resource path to avoid a 404 Not Found error response.

Minor and micro API versions (such as 1.1 or 1.0.1) should not be used. These may update frequently with backward-compatible API changes.

Any future backward-incompatible changes will only occur under a new major version. This might include the addition, removal, reorganization, or renaming of endpoints.