Pagination

Some Schiphol APIs divide large result sets into pages. Pagination keeps response sizes manageable and allows clients to retrieve results incrementally.

The parameters supported by an endpoint are defined in its OpenAPI specification. Common pagination parameters include:

If an endpoint does not expose pageSize, the API controls the page size.

Request a page

Add the page parameter to the request URL:

GET /resources?page=0

To request the next page:

GET /resources?page=1

Keep the same filtering and sorting parameters on every request. Changing them creates a different result set and can cause items to be skipped or returned more than once.

HATEOAS and pagination links

Pagination uses Hypermedia as the Engine of Application State (HATEOAS). Instead of requiring a client to calculate every pagination URL, the API describes the available navigation actions with links in the response.

These links are provided in the HTTP Link response header rather than in the JSON response body. Following the server-provided links keeps the client independent of URL construction details and ensures that filters, sorting, and fixed-point-in-time values remain part of subsequent requests.

Paginated responses can include an HTTP Link response header. Each link has a rel value that describes its destination:

For example:

Link: <https://api.example.com/resources?page=0>; rel="first",
      <https://api.example.com/resources?page=1>; rel="prev",
      <https://api.example.com/resources?page=3>; rel="next",
      <https://api.example.com/resources?page=8>; rel="last"

Follow the URL from the next relation instead of constructing the next URL yourself. The API includes the relevant filters and fixed-point-in-time values in generated links and may URL-encode their values.

The first page does not have a prev link, and the last page does not have a next link. A response can omit the Link header when there are no other pages.

Process all pages

A typical client should:

1. Request the first page using page=0 or the endpoint's default.
2. Process the response successfully before requesting another page.
3. Read the HTTP Link response header.
4. Follow the URL with rel="next".
5. Stop when the response has no next relation.

Do not rely on the number of items in a response to determine whether another page exists. Use the Link header when it is provided.

Empty pages and errors

An empty or out-of-range page can return 204 No Content, depending on the endpoint. Other APIs may return an empty collection. Consult the endpoint's OpenAPI specification for its exact behavior.

Invalid page numbers or page sizes can return 400 Bad Request. Keep page values non-negative and respect any documented page-size limits.