Getting started¶
The Awaretrain API is a REST API
for interacting with the Awaretrain platform, primarily using JSON
data in requests and responses. Each API resource has its own URL (called an endpoint) and depending on the request method ( e.g. GET
, POST
, PUT
etc.) an action is performed.
On this page, you will find the necessary information on how to get started with the Awaretrain API.
Versioning¶
The API is versioned, in which we take great care to ensure changes to the API are backwards compatible and will not break any existing integrations.
The version is denoted in the URL: https://api.awaretrain.com/public/<version>
.
An OpenAPI specification is available for each version.
Version | OpenAPI specification | Release date |
---|---|---|
v1 | HTML, JSON, YAML | - |
Authentication¶
All endpoints of the API require authentication and therefore a valid API key. See API keys on how to create and manage API keys for your organisation.
Each request is required to contain an Authorization
header with its value set to Bearer <api token here>
.
Scopes¶
Every API key has one or more scopes assigned, granting access to specific API resources and operations. See scopes for an overview of all available scopes.
Warning
Make sure to keep the assigned scopes to an absolute minimum of what is required for its intended purpose and set an expiry date of around a year. This minimises potential damage in case the API key falls in the hands of attackers.
Rate limits¶
Rate limits are enforced on the Awaretrain API to prevent abuse and keep the systems operational. These limits are enforced per API key, not per IP address.
In case you exceed the allowed number of requests, an HTTP 429 Too Many Requests
response will be returned with a Retry-After
header containing the number of seconds after which to try again.
Currently, we allow up to 1 request per second (60 / minute) using a sliding window approach, but this may change in the future.
Handling errors¶
In case of an error, a JSON response is returned that is formatted according to RFC7807.
Though the status code should be the primary indication of what went wrong, the response can contain useful details as to what caused the problem.
{
"type": "https://api.awaretrain.com/errors/6b7454c2-78ce-4623-9301-f62dd3f27d3e",
"title": "Example error",
"detail": "This is an example error.",
"status": 403
}
Pagination¶
Some endpoints return paginated data. Those endpoints accept a few query parameters to control, for example, what page and how many results are returned.
Parameter | Type | Default | Description |
---|---|---|---|
page | integer | 1 | Page number (starting from 1). |
perPage | integer | 25 | The number of results returned per page. The maximum value is 1000 . |
The response will contain the following properties:
Property | Type | Optional | Description |
---|---|---|---|
page | integer | Current page number. | |
perPage | integer | Displayed number of items per page. | |
total | integer | Total number of items (over all pages). | |
extra | object | Optional object containing extra data. | |
data | array | Array of objects containing the page data. |
Common problems¶
HTTP 400 Bad Request response¶
This response indicates that there is something wrong with the request.
- Check if the response contains a message that might help you locate the problem.
- In the case of query parameters in the URL, make sure they have correct values and its values are encoded properly.
- In case of a request body, make sure the request data is valid JSON and the request has the
Content-Type: application/json
header set. - In case of a multipart request. Make sure the
Content-Type: multipart/form-data
header is set and contains a valid boundary. Also make sure that the contents of each part have the correctContent-Type
header.
HTTP 401 Unauthorized response¶
This response indicates that the request is missing the Authorization
header or that its value is not formatted correctly.
- Check that the
Authorization
header value starts withBearer
See authentication for more information.
HTTP 403 Forbidden response¶
This response can indicate several things:
- Your IP address is not whitelisted
- The API key used in the request has expired
- The API key used in the request is not valid
- The API key used in the request does not have the required scopes to access the requested resource
If the API key is valid, has not expired and has the correct scopes; make sure the Authorization
header is sent correctly. See authentication for more details.
HTTP 422 Unprocessable Entity response¶
This response indicates that the request contents did not pass validation.
In most cases, the response should contain a list of violations that were found during validation.
{
"type": "https://api.awaretrain.com/errors/validation",
"title": "Validation Failed",
"status": 422,
"violations": [
{
"propertyPath": "name",
"title": "Name cannot be blank.",
"template": "Name cannot be blank.",
"parameters": []
}
]
}
HTTP 429 Too Many Requests response¶
You have made too many requests in a short period of time. Please see rate limits for more information about how we apply rate-limiting.