This pages contains general documentation about the REST API. Use the links on the right to navigate to specific resources.
The API uses the JSON format. Unless specified otherwise, all requests and
response should have the Content-Type: application/json header.
The API uses the standard HTTP verbs to perform CRUD operations (Create, Retrieve, Update, Delete) on resources, following standard RESTful API practices.
Find below a quick summary of how HTTP verbs are used in the API:
| Verb | Description |
|---|---|
GET |
Used for retrieving a resource or a collection of resources. |
POST |
Used for creating a new resource . |
PUT |
Used to perform a full update of a resource (replacing the resource by the JSON data provided in the request). |
DELETE |
Used for deleting resources. |
In GET methods, you may provide filter information. flat approach (/{id}) or the query string approach (?date=2014-12-15) are used.
In case of error, the API will send a JSON response with the list of errors. Each error has a human-readable message and a code. The code identifies the error type and can be used to handle specific errors differently or for translation purposes.
For example :
HTTP/1.1 400 Bad Request
{
"errors": [
{
"message": "JSON parsing error.",
"code": 10000
}
]
}
All dates returned by the API are in UTC and use the ISO-8601 format (ex:
2015-02-15). When a date represents a day, it’s set at 0 hour, 0 minute and 0 second.
To interact with the API, your client will need to be authenticated. This is done by using the Authorization header with the username and password of the client and gives something that looks like:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
A user who is part of a organization can read data from the same organization and public data from other organizations, but can only write data from the same organization. In this case, request will require an authentication (user login).
The GET methods on the resources return the first page and a number of items per page.