API Conventions

The Skylark API uses a RESTful approach, performing operations over stateless HTTP calls and using URLs as identifiers for objects and relationships.

Data format

Requests and responses to Skylark API are made in JSON format.

Dates and datetimes are specified in RFC 3339/ISO 8601 format.

Response codes

Skylark commonly uses these standard HTTP response codes.

CodeDescription
200 OKThe request was successful and a response has been provided
201 CreatedThe request was successful and a new object was created.
204 No ContentThe request was successful, but there is no response body. This the typical response for DELETE calls.
400 Bad RequestThe parameters, data format, or content of the request was incorrect. The response body contains more detail (see Error Reporting, below)
401 UnauthorizedThe request was made anonymously but requires an authenticated user, or the given authentication details were invalid or expired.
403 ForbiddenThe authenticated user does not have the permissions required to perform the API call
404 Not FoundThe request does not exist, or no object with the given unique identifier exists
410 GoneThe object requested has been deleted and is no longer available from the API
500 Internal Server ErrorAn internal problem has caused no response to be generated. Please contact support.

Error Reporting

When an 400 Bad Request error occurs, a JSON response is returned such as this:

{
    "form_validation_errors": null,
    "error": null,
    "skylark_error_code": "NO_VIEWING_RECORD_PROVIDED"
}
  • error: a plain-text description of the error
  • skylark_error_code: standardised skylark error codes are shown here. Possible values are documented for each API.
  • form_validation_errors: if there are any validation errors with incoming data, they are detailed here. The error code is set to "FORM_VALIDATION_ERRORS"

Authentication

APIs require an authenticated user in the following cases:

  • They are user management or content entitlement APIs, and require a user to operate on
  • They are administrative APIs, and require a user with the correct permissions for the request

Authentication details are provided in the standard HTTP Authorization header. Authentication is done via Amazon Cognito.

Languages

API calls for entities that can be translated into multiple natural languages respect the Accept-Language header.

For requests to read data, all languages in the header will be tried, with the first available supported language being returned. If the wildcard * is specified in the Accept-Language header, any available language will be returned, with the site default language being preferred.

The language of the response will be given in the Content-Language header.

If the resource exists but has no translation in any of the languages specified in the Accept-Language header, a 406 Not Acceptable response will be returned. If fallback behaviour is not desired, specify only a single language in the Accept-Language header.

For requests to write data, only the highest priority language in the Accept-Language header will be considered. If no Accept-Language is given, the site default language will be assumed. If the given language is not enabled in the Skylark configuration or is a wildcard, a 406 Not Acceptable response will be returned.

Endpoint Conventions

Most Skylark API endpoints follow the pattern below.

All API endpoints require a trailing slash. They support field restriction and expansion to control the amount of data returned.