Pagination

Pagination is a feature introduced with v2 endpoints that return more results than can be returned in a single response. Pagination is required in cases where there are more matching results than the max pageSize defined for a resource. Some endpoints on previous versions could return a lot of data in response to a single request, which can be problematic to handle for clients. With pagination large results will be split into multiple, more manageable pages.

Currently the following endpoints support paging:

GET api/v2/items
POST api/v2/items

These endpoints will accept the following parameters:

pageSize: the max number of items returned in a single response. If no value is set for this parameter, the default value of 1000 will be used. Max allowed pageSize is 10000.

pageToken: set to the value of “forwardToken” from the previous request’s response, to get the next page of the results. Set the value of “backwardToken” for the previous page of results. This parameter will not have any value for the initial request.

sortField: name of the field the response should be sorted by. For most scenarios this could be left out, to fall back to the default value. (eg. NOBB number for api/v2/items endpoints). For the item endpoints, supported fields are currently NobbNo, OwnerParticipantNo and Created.

sortOrder: the order to sort the response by. Can be set to “asc” for ascending order, or “desc” for descending order. The default value is “asc”.

Response from endpoints that supports paging will include the following values, as HTTP headers:

x-totalHits: the total number of items in the result.

x-forwardToken: an opaque string that should be passed as the pageToken parameter to get the next page of the results. If this response header is not present, you have all the results, and no more pages are available.

x-backwardToken: an opaque string that should be passed as the pageToken parameter to get the previous page of the results.

Note 1: x-forwardToken and x-backwardToken have a lifetime of 5 minutes, so subsequent calls must be made within this timespan. If the token has expired it will not be considered, which means the response will be returned from the first page again.

Note 2: Please be aware that if any search parameter is modified, including filters, pageSize, sortField, or sortOrder, the request will be considered as a new initial request. This means that the search process will be restarted, and any previous page or context will be disregarded. To ensure accurate and consistent results, it's essential to maintain the integrity of the original search parameters throughout the pagination process.

In the example below we are making a request to an endpoint, where the result consists of three pages, since we have defined a pageSize of 100 and the the x-total-hits is 300. The response will be ordered by NOBB number, ascending, which is the default for the resource in this example.

https://export.byggtjeneste.no/api/v2/items?from=2024-02-01&pageSize=100

Response headers

x-total-hits: 300

x-forward-token: RnwyfDUzNjA1NTU3fDUzNjA1NTU3fDYzODQyMzcyMTc4MDIxNDc4Ng==

To get the next page of the result we pass the forward-token from the response to the initial request.

https://export.byggtjeneste.no/api/v2/items?from=2024-02-01&pageSize=100&pageToken=RnwyfDUzNjA1NTU3fDUzNjA1NTU3fDYzODQyMzcyMTc4MDIxNDc4Ng==

Response headers

x-total-hits: 300

x-backward-token: QnwxfDUzNjA1NTYxfDUzNjA1NTYxfDYzODQyMzcyMTc4MDIxNDc4Ng==

x-forward-token: RnwzfDU3MzEzNDIzfDU3MzEzNDIzfDYzODQyMzcyMTc4MDIxNDc4Ng==

To get the next page of the result we pass the forward-token from the response to the previous request.

https://export.byggtjeneste.no/api/v2/items?from=2024-02-01&pageSize=100&pageToken=RnwzfDU3MzEzNDIzfDU3MzEzNDIzfDYzODQyMzcyMTc4MDIxNDc4Ng ==

Response headers

x-total-hits: 300

x-backward-token: RnwyfDUzNjA1NTQyfDUzNjA1NTQyfDYzODQyMzczMjkyNjAwMTg1Mw==

x-forward-token:

Since no forward token is present as a response header, we have all the results.

Pagination example

Initial request

Second page

Third page