Pagination

Introduction

When an endpoint provides a list of items, it usually involves a pagination. In the Toornament API, this is performed by using the Range HTTP header.

The request must provide a header with the range of elements requested. The response will return a partial result with a header containing the number of returned elements and the total number of elements.

A unit does not necessarily identify a resource type.

Request

The request on a range-sensitive endpoint MUST provide a Range HTTP header. If the header is not present, the endpoint will return a 400 status code. The header is formatted using the following pattern:

GET /endpoint HTTP/1.1
Host: api.toornament.com
...
Range: {unit}={from}-{to}

Example

# Requests the first 50 tournaments
Range: tournaments=0-49

Response

The response of a range-sensitive endpoint will return a 206 Partial Content with the elements requested by the range in the response body.

An additional Content-Range header will also contain the range of the items returned and the total number of items using the following pattern:

HTTP/1.1 206 Partial Content
Content-Type: application/json
...
Content-Range: {unit} {from}-{to}/{total}

Example

# Returns the first 50 tournaments
Content-Range: tournaments 0-49/114

If the requested range starts on a valid offset but exceeds the maximum number of items, a partial response will still be returned.

Example

# Requests 50-99 range on a collection of 75 items
Content-Range: tournaments 50-74/75

Errors

Missing range

If the range header is missing on a range-sensitive endpoint, it will return a 400 Bad Request.

Mal-formatted range

If the range header contains a mal-formatted value, the endpoint will return a 400 Bad Request.

Out of range

If both range offsets (from and to) exceed the number of items available, the endpoint will return a 416 Range Not Satisfiable.

Example

# on a list of 30 tournaments
Range: tournaments=50-99

Invalid range

If the first offset is higher than the second, the endpoint will return a 416 Range Not Satisfiable.

Example

Range: tournaments=99-50

Range size limit

If the size of the range exceeds the maximum range size allowed, the endpoint will return a 416 Range Not Satisfiable.

Example

# maximum range size allowed is 20
Range: tournaments=0-99

Unknown unit

If the range unit is unknown, the endpoint will return a 416 Range Not Satisfiable.

Example

# expected unit is tournaments
Range: foo=0-19