Overview

Introduction

The Tapglue API is created with a REST architecture in mind. It is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which can be understood by off-the-shelf HTTP clients.

You can also directly access the API Reference for the detailed low-level documentation.

API Compatibility

The API will evolve over time. Future versions of this API may add new endpoints or parameters. In order to keep older clients working, the behavior and return value of APIs with given parameter values will not change from the currently documented behavior and return values.

If we become aware that a certain version of the API contains something that's critical for the security of our users we reserve the right to give you a short notice so you can upgrade to version that will fix the issue. We will work with you to overcome any possible issues in regards to upgrading to a fixed version of the API.

SSL Only

We require that all requests are done over SSL, thus all access is over HTTPS, and accessed from the api.tapglue.com domain. Unencrypted HTTP is not supported.

JSON Only

All data is sent and received as JSON, including errors.

While we'll do our best not to return 4xx and 5xx errors, we cannot control external factors that stand between our servers and your clients. As such, be prepared to receive non-JSON from third parties (such as a CDN provider) in case something goes wrong.

UTF-8 Encoding

Every string passed to and from the Tapglue API needs to be UTF-8 encoded. For maximum compatibility, normalize to Unicode Normalization Form C (NFC) before UTF-8 encoding.

Date Format

All dates and timestamps are returned in RFC 3339 format:

YYYY-MM-DDTHH:mm:ssZ

2015-01-28T23:25:15Z02:00

Blank Fields

Blank fields are being omitted instead of included as null.

HTTP Verbs

Method	Description
`GET`	Retrieve a resource
`POST`	Create a resource
`PUT`	Update a resource
`DELETE`	Delete a resource

HTTP Redirects

The Tapglue API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

Status Code	Description
`301`	Permanent redirection. The URI you used to make the request has been superseded by the one specified in the `Location` header field. This and all future requests to this resource should be directed to the new URI.
`302` `307`	Temporary redirection. The request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests.

User Agent Required

All API requests MUST include a valid User-Agent header. Requests with no User-Agent header will be rejected. A good practice is to send the application name and version for the User-Agent header value, this allows us to contact you if there are problems.

User-Agent: Awesome-Tapglue-App 1.0

Cross Origin Resource Sharing

We support cross-origin resource sharing (CORS) to allow you to interact securely with our API from a client-side web application (though you should remember that you should not expose your secret API key in any public applications client-side code).