Skip to main content

API notes

Filters​

Endpoints for listing resources support filtering for some values. For example, the List all games endpoint has a filter[studio.id] query parameter, which, when specified, will return only games from the studio with the given studio id.

Sorting​

Responses for endpoints for listing resources are always sorted. The value to sort items by can be controlled with the sort query parameter. This parameter also controls the sort order (ascending or descending). The values for the parameter generally have the format [property]:[order] where [properties] is one of the items' properties (for example, title for a game's title) and [order] is either asc (for ascending order) or desc (for descending other).

Pagination​

Endpoints for listing resources are paginated. You can control the number of items to be returned by setting the page[size] query parameter. This parameter can be at most 100.

The meta.total property in the response payload always stands for the total number of items available; that is, the number of items that would be returned without pagination. This parameter can be used to determine whether there are more items to be fetched. Further pages can be fetched via the page[offset] query parameter. The value indicates how many items are to be skipped.

Note that pagination is applied after sorting and filtering. The meta.total property is also relative to filtering.

Some endpoints have an expand[] query parameter, which can be used for returning related objects. For example, a game contains a studio property. Normally this will refer to the studio id, but by passing expand[]=studio, you get the full studio object.

Rate-limiting​

Repeated usage of the API in a short period of time can lead to you being rate-limited. If this happens, your requests will get a 429 Too Many Requests response. Make sure your code can handle that failure scenario and that it's not calling Organization API too often.