JSON: API Interface

Some requests using the JSON:API format accept additional query string parameters. Inclusion of related resources in the response can be requested with the include query string parameter. Multiple entities can be specified by separating them with a comma (U+002C). Each endpoint definition specifies which includes can be requested.

Examples:

GET /user?include=usergroup,accounts
          GET /user/[id]?include=usergroup,accounts

Alternatively, related resources on a single resource can be requested through a separate endpoint:

GET /user/[id]/usergroup

Pagination

When making requests to endpoints which can return more than one entity, results are paginated. The number of results per page and the requested page can be adjusted with the page[limit] and page[offset] query string parameters. When the page limit is set to -1, all results are returned. The links element in the JSON response contains references to URLs which can be used to navigate the resultset. The meta element in the JSON response contains a reference to the total number of items in the resultset.

Example:

GET /user?page[limit]=50&page[offset]=2

Sorting

It is possible to sort results by using the sort query string parameter. A descending sort order can be requested by prefixing a hyphen (U+002D).

Example:

GET /user?sort=-username

Filtering

To filter results, use the filter[attribute] query string parameter. A filter can also use related entities (which don't have to be included in the request with the include parameter).

The following formats are supported for filtering results:

Token

Description

Example

^

Field starts with

filter[name]=^John

$

Field ends with

filter[name]=$Smith

~

Field contains

filter[favorite_cheese]=~cheddar

<

Field is less than

filter[lifetime_value]=<50

>

Field is greater than

filter[lifetime_value]=>50

>=

Field is greater than

filter[lifetime_value]=>50

>=

Field is greater than or equals

filter[lifetime_value]=>=50

<=

Field is less than or equals

filter[lifetime_value]=<=50

=

Field is equal to

filter[username]==Specific%20Username

!=

Field is not equal to

filter[username]=!=common%20username

[...]

Field is one or more of

filter[id]=[1,5,10]

![...]

Field is not one of

filter[id]=![1,5,10]

NULL

Field is null

filter[address]=NULL

NOT_NULL

Field is not null

filter[email]=NOT_NULL

Example:

GET /user?filter[usergroup.permissions]=~MANAGE_USERS&filter[email_address]=$example.com

How did we do?