Pagination Links clarification

Owned by Nigel Somerfield
Sept 20, 2024
3 min read

Issue identified

There is a potential for confusion between the Pagination and Links section of the NZ Banking API Standards. The Pagination section describes the logic for each of the Links as:

  • A link to the next page of resources in the Links.Next field of the response if a subsequent page of resource records exists. The absence of a Next link would indicate that the current page is the last page of results.

  • A link to the previous page of resources in the Links.Prev field of the response if a previous page of resource records exists. The absence of a Prev link would indicate that the current page is the first page of results.

  • A link to the first page of results in the Links.First field

  • A link to the last page of results in the Links.Last field.

  • A "Self" link to the resource in the Links.Self field as with all other API responses, as described in the Links sections.

Whereas, the Links section states:

If an API provides a paginated response, the Links section must also contain the members "First", "Prev", "Next" and "Last".

Links are mandatory, but not always populated

On the first page of a set of paginated results, a Links.Prev is nonsensical, and similarly a Links.Next is nonsensical on the last page.

The Pagination section has the correct logic, and the Links section should be interpreted as "All links in paginated response must be provided, when it is logically consistent to do so". That is, Links.Prev and Links.Next are conditionally required, whenever there are Links that will be meaningful to the API consumer.

Illustrative examples

To demonstrate the use of Links, in a manner that is consistent with the Pagination requirements, consider a list of accounts that contains 5 pages, each containing 25 accounts. The following subsections include examples of Links that an API Provider would be expected to return.

Example data is not included in the response and the size of the pages is not included in the example requests (or Link URIs) for brevity.

Example 1 - first page of results

Request: GET /accounts (or GET /accounts?page[number]=1)

Response:

{ "Data" : { ... }, "Links": { "Self": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=1", "First": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=1", "Next": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=2", "Last": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=5" } }

Note: No Links.Prev is included, since there is no prior page of results to retrieve.

Example 2 - last page of results

Request: GET /accounts?page[number]=5

Response:

{ "Data" : { ... }, "Links": { "Self": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=5", "First": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=1", "Prev": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=4", "Last": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=5" } }

Note: No Links.Next is included, since there is no further page of results to retrieve.

Example 3 - third page of results

Request: GET /accounts?page[number]=3

Response:

{ "Data" : { ... }, "Links": { "Self": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=3", "First": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=1", "Next": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=4", "Prev": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=2", "Last": "https://api.provider.co.nz/open-banking-nz/v3.0/accounts?page[number]=5" } }