Pagination

When a response includes many results, API endpoints that support pagination will return a subset of the results based on request parameters. For example, GET /api/v1/users will only return 25 items by default even though there may exist thousands of users on the server. This makes the response easier to handle for the server as well as for people.

Using link headers

When a response is paginated, the response headers will include a link header. If the endpoint doesn't support pagination, or if all results fit on a single page, the link header will be omitted. The information in the header can be used to request additional pages of data.

When included, the link header will look something like this:

link: <https://example.park46.se/api/v1/users?page=1&per_page=10>; rel="first", <https://example.park46.se/api/v1/users?page=4&per_page=10>; rel="prev", <https://example.park46.se/api/v1/users?page=6&per_page=10>; rel="next", <https://example.park46.se/api/v1/users?page=14&per_page=10>; rel="last"

The header value provides:

• the URL of the first page, followed by rel="first";
• the URL of the previous page, followed by rel="prev";
• the URL of the next page, followed by rel="next";
• the URL of the last page, followed by rel="last".

In some cases, only a subset of these links may be available. For example, the link to the previous page won't be included on the first page of results.

Pagination parameters

The URLs in the link header use query parameters to indicate which page of results to return. Each paginated endpoint supports the following two parameters:

• page (integer)

  The page of results to return.

• per_page (integer)

  The number of items to return per page.