Using an API

This document outlines the conventions used for consuming APIs built with Apia.

Requests

Consumers can make requests to any resource provided by the API (and listed as a route).

/api/v1/users/list

In addition to the path, requests must be made using the correct HTTP method. For example, a user list may well be implemented as a GET request whereas a user creation may well be implemented to require POST.

All successful requests will respond with a 2xx status code.

Unless otherwise documented, all requests will return a JSON hash (with the application/json content type).

To provide data to a request, there are few options - you should choose an option based on the method required for the endpoint.

Querystring - you can provide query strings with your request (for example ?name=Dave). This is useful for GET or HEAD requests.
JSON - you can provide a JSON hash in the body of the request (with the application/json content type). Recommended for all non-GET/HEAD requests.
Form-encoded - you can provide form-encoded data (with the application/x-www-form-urlencoded content type). If you must.

Authentication

At present, the only (documented) supported authentication mechanism for Apia APIs are using a bearer token in the Authorization header. Therefore, you must include a header as shown below for each request.

Authorization: Bearer {supplied-api-token}

Errors

If a request cannot be completed for any reason you should receive a 4xx or 5xx status code. In the majority of cases, errors will contain a JSON body with details of the error (it is possible that some 502/503 errors may not return JSON). Errors generated by Apia will always follow the following structure and will contain an X-API-Schema: json-error header to let you know how you can pass it.

{
  error: {
    code: 'example_error', # A code to describe the error
    description: 'An example error', # A human readable description of the error
    detail: {
      # Contains arbitary information that may be useful for the specific
    }
  }
}