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.
Code | Description |
---|---|
200 OK | The request was successful and a response has been provided |
201 Created | The request was successful and a new object was created. |
204 No Content | The request was successful, but there is no response body. This the typical response for DELETE calls. |
400 Bad Request | The parameters, data format, or content of the request was incorrect. The response body contains more detail (see Error Reporting, below) |
401 Unauthorized | The request was made anonymously but requires an authenticated user, or the given authentication details were invalid or expired. |
403 Forbidden | The authenticated user does not have the permissions required to perform the API call |
404 Not Found | The request does not exist, or no object with the given unique identifier exists |
410 Gone | The object requested has been deleted and is no longer available from the API |
500 Internal Server Error | An 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 errorskylark_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.