When issuing a GET request on a collection containing more than 1 page (e.g. /events),
a collection is returned. Links to the first, the last, previous and the next page in the collection are displayed as well as the
number of total items in the collection.
Cursor pagination is a technique used for navigating through large datasets efficiently. It allows you to retrieve a specific subset of results from a collection by using a cursor value that represents the position within the collection. The cursor serves as a reference point for fetching the next or previous set of results.
Efficient Navigation: Cursor pagination eliminates the need to fetch the entire dataset at once, making it more scalable and faster. You can retrieve data in smaller, manageable chunks based on the cursor values.
Consistent Results: Each page of results in cursor pagination is stable and doesn’t change even if new items are added or removed from the collection. This ensures that you get consistent and reliable results.
Flexibility: Cursors can be used to navigate forwards and backwards in the collection without impacting performance.
To use cursor pagination with our API, follow these instructions:
Make a request to retrieve the initial page of results. The response will be a JSON-LD document that includes a hydra:next
attribute with the URI for the next page. The URI already includes the cursor attribute.
To retrieve the next page of results, make a GET request to the URI provided in the hydra:next
attribute. This URI will automatically include the cursor value for the next page.
If you want to navigate to the previous page, you can use the hydra:previous
attribute in the JSON-LD response. It will contain the URI for the previous page, including the cursor value.
You can continue making requests to the hydra:next
and hydra:previous
URIs to navigate through the paginated results, based on your requirements.
Make sure to update your request headers to include the necessary headers for JSON-LD content negotiation, such as Accept: application/ld+json
or Content-Type: application/ld+json
.
By following these instructions, you can effectively navigate through the paginated results using the cursor values provided in the hydra:next
and hydra:previous
attributes, without the need to manually include the cursor in your requests. This simplifies the pagination process and enhances the usability of our API.
By default, the API uses offset-based pagination. If you want to switch to cursor pagination, you need to include an additional header in your request. Set the X-Pagination-Style
header with the value "cursor"
to enable cursor pagination. If not specified, the API will assume offset-based pagination.
After enabling cursor pagination, the API response will no longer include the hydra:totalItems
field by default. Retrieving the total count can be resource intensive and impact response times, especially for large datasets. However, if you need the hydra:totalItems
information, you can include an additional header in your request. Set the X-Pagination-Enable-Partial
header with the value 0
to indicate that the response should include extra information, including the hydra:totalItems
count. Please be aware that enabling this feature may impact API response times, as the backend needs to perform a count operation on the dataset.
If you require the hydra:totalItems
count, please consider the potential impact on API response times.
Note: We only support cursor pagination for the following endpoints:
GET /taxpayers/{taxpayerId}/invoices
GET /taxpayers/{taxpayerId}/invoices/line-items
GET /taxpayers/{taxpayerId}/invoices/{invoiceId}/line-items
GET /invoices/{invoiceId}/line-items
GET /taxpayers/{taxpayerId}/invoices/payments
Feel free to reach out if you have any further questions or need additional assistance!