Request and Response format

Request and Response format

Notice: The format described here is not implemented in all our APIs. Some API versions (like Observation V1 to V4) could differ partially or fully from this document. Please consult our API Documentation to be sure.

Response status code

The HTTP response status code is the first description of the response content.

Response content type

You can expect several response content types. It could be eather empty or an object but NEVER an array. When a json object is returned, the response data is available in a data property.

Empty response

Mainly for HTTP status code 204

Exemple:

An endpoint that return the difference between two arrays

// Request with arrays [1,2,3] and [1,2,3] will have a response with HTTP
// Status code: 204 No Content

// Request with arrays [1,2,3] and [1] will have a response with HTTP Status
// code: 200 OK
{
  "data": {
    "differences": [2, 3]
  }
}

Created response

Mainly for HTTP status code 201. Created responses of POST requests are returning an empty payload and a Location header containing the endpoint to call for retreiving the newly created content as specified in RFC 7231 « HTTP/1.1 Semantics and Content ».

Simple object response

Mainly for HTTP status code in the 2XX range

data: Response data

// Requested user will be sent with HTTP Status code: 200 OK
{
  "data": {
    "id": 4561385,
    "username": "john.doe",
    "email": "john.doe@mail.com",
    "firstname": "John",
    "lastname": "Doe",
    "country": "Switzerland",
    "preferred_lang": "fr-CH"
  }
}

List of objects

Sorting

When requesting list of objects, sorting is possible by using query parameters.

Note: Keep in mind that not all fields are allowed for sorting, the allowed fields are listed on the API Documentation.

The query parameter validation is applying those rules.

It is possible to use either the simple of complete sort format (simple is sort=id and complete is sort[id]=asc)
When a simple sort format is used the asc order is assumed
It is not possible to use both simple and complete sort format (sort=id and sort[date]=asc will return error 400)

So a sort could typically take the following form:

sort=id or sort[id]=asc: sort by ascending id
sort[id]=desc: sort by descending id
sort=date,quantity,id: sort by ascending date, then by ascending quantity, then by ascending id
sort[date]=desc&sort[quantity]=asc&sort[id]=asc: sort by descending date, then by ascending quantity, then by ascending id

Simple lists of objects

Mainly for HTTP status code in the 2XX range. By default all lists are returned without totals.

data: List of items

// Requested firstnames will be sent with HTTP Status code: 200 OK
{
  "data": [
    "Alice",
    "Bob",
    "Charlie",
  ]
}

To have the totals returned, you need to add the query parameter with_total=true. The totals will then be set in the X-Total response header.

X-Total: 400

Paginated list of object

Mainly for HTTP status code in the 2XX range. Pagination is triggered by using offset and/or limit query parameters. By default all lists are returned without totals or paging details.

data: List of items in the page

// Requested page of 2 firstnames will be sent with HTTP Status code: 200 OK
{
  "data": [
    "Alice",
    "Bob"
  ]
}

To have the totals returned, you need to add the query parameter with_total=true. The totals will then be set in the X-Total response header.

X-Total: 400

To have the pagination links returned, you need to add the query parameter with_paging=true. The paging will then be set in the Link response header.

Link: <https://endpoint_url?offset=40&limit=20>;rel="prev", <https://endpoint_url?offset=80&limit=20>;rel="next", <https://endpoint_url?offset=0&limit=20>;rel="first", <https://endpoint_url?offset=380&limit=20>;rel="last"

Filtered list of object

Mainly for HTTP status code in the 2XX range. Filtering is triggered by using one or more filter query parameters. By default all lists are returned without totals.

data: List of filtered items

// Requested firstnames containing the string `John` will be sent with HTTP
// Status code: 200 OK
{
  "data": [
    "John",
    "Johnathan"
  ]
}

To have the totals returned, you need to add the query parameter with_total=true. The totals will then be set in the X-Total and X-Filtered-Total response headers.

X-Filtered-Total: 27
X-Total: 400

You can filter a list of object by using query parameters. Supported operations are:

is_null: the value is NULL
is_not_null: the value is NOT NULL
eq: the value is equal to
i_eq: the value is equal to (case insensitive)
w_eq: the value is equal to (support wildcard)
iw_eq: the value is equal to (case insensitive, support wildcard)
neq: the value is NOT equal to
i_neq: the value is NOT equal to (case insensitive)
w_neq: the value is NOT equal to (support wildcard)
iw_neq: the value is NOT equal to (case insensitive, support wildcard)
gt: the value is greather than
gte: the value is greather than or equal to
lt: the value is less than
lte: the value is less than or equal to
in: the value is included in
not_in: the value is NOT included in
starts_with: the value starts with
i_starts_with: the value starts with (case insensitive)
w_starts_with: the value starts with (support wildcard)
iw_starts_with: the value starts with (case insensitive, support wildcard)
contains: the value contains
i_contains: the value contains (case insensitive)
w_contains: the value contains (support wildcard)
iw_contains: the value contains (case insensitive, support wildcard)
ends_with: the value ends with
i_ends_with: the value ends with (case insensitive)
w_ends_with: the value ends with (support wildcard)
iw_ends_with: the value ends with (case insensitive, support wildcard)

Note: Keep in mind that not all operations are allowed on all fields, the allowed operations are listed on the API Documentation.

Here are the operations possible on each field type:

Operation	boolean	date	number	string
`is_null`	x	x	x	x
`is_not_null`	x	x	x	x
`eq`	x	x	x	x
`i_eq`				x
`w_eq`				x
`iw_eq`				x
`neq`	x	x	x	x
`i_neq`				x
`w_neq`				x
`iw_neq`				x
`gt`		x	x
`gte`		x	x
`lt`		x	x
`lte`		x	x
`in`			x	x
`not_in`			x	x
`starts_with`				x
`i_starts_with`				x
`w_starts_with`				x
`iw_starts_with`				x
`contains`				x
`i_contains`				x
`w_contains`				x
`iw_contains`				x
`ends_with`				x
`i_ends_with`				x
`w_ends_with`				x
`iw_ends_with`				x

The query parameter validation is applying those rules:

It is possible to use either the simple of complete filter format (simple is id=123 and complete is id[eq]=123)
When a simple filter format is used the eq operation is assumed
It is not possible to use both simple and complete filter format for a same field (id=123 and id[eq]=213 will return error 400)
Filters are generally applied additionally (filter1 and filter2 and filter3) unless described otherwise in the API Documentation.

So a filter on a numeric id could typically take the following form:

id=123 or id[eq]=123: id is 123
id[neq]=123: id is not 123
id[in]=123,456,678: id is one of 123, 456 or 678
id[not_in]=123,456,678: id is not one of 123, 456 or 678
id[gt]=100: id is greater than 100
id[gte]=100: id is greater than or equal to 100
id[lt]=100: id is lower than 100
id[lte]=100: id is lower than or equal to 100

Wildcard support

When using an operation with wildcard support (begining with w_ or iw_) the following caracters are considered a wildcard:

? Only one caracter
* One or more caracters

Totals and paging links without data

Since the generation of totals might significantly impact the response time of your request you can request the totals separatly by doing a HEAD request with the exact same parameters you are using in your GET request. Don’t forget to set the with_total=true and/or with_paging=true to have que nedded informations.

Errors

Mainly for HTTP status code in the 4XX range

error: Error name (machine readable)
error_description: Human readable message that could be presented to the user
data (optionnal): additionnal data about the error

// The AlreadyExistError catched will be forwarded with HTTP Status
// code: 409 Conflict
{
  "error": "already_exists_error",
  "error_description": "There is already a User with this username in the database",
  "data": {
    "username": "john.doe",
  }
}

// The TokenExpiredError catched will be forwarded with HTTP Status
// code: 401 Unauthorized
{
  "error": "token_expired_error",
  "error_description": "Token is expired"
}

if an error code is provided it should be an application-scoped error code and not the HTTP Status code replication

// The code 4503 could allow the developer to pinpoint exactly the piece of
// code that generated the error if there is multiple possible occurences of
// this error. It can also be a id referencing an error occurence in an error
// tracking tool.
{
  "error": "forbidden_error",
  "code": 4503,
  "error_description": "Edit is not authorized on archived item"
}

API Request and Response format

Request and Response format

Table of Contents

Response status code

Response content type

Empty response

Created response

Simple object response

List of objects

Sorting

Simple lists of objects

Paginated list of object

Filtered list of object

Wildcard support

Totals and paging links without data

Errors

API Request and Response format

#Request and Response format

Table of Contents

#Response status code

#Response content type

#Empty response

#Created response

#Simple object response

#List of objects

#Sorting

#Simple lists of objects

#Paginated list of object

#Filtered list of object

#Wildcard support

#Totals and paging links without data

#Errors

Request and Response format

Response status code

Response content type

Empty response

Created response

Simple object response

List of objects

Sorting

Simple lists of objects

Paginated list of object

Filtered list of object

Wildcard support

Totals and paging links without data

Errors