Pagination

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.

All endpoints that support this operation have a query parameter defined by: 
  - `itemsPerPage` The number of items per page (default: 20, max: 1000)
  - `page` The collection page number

  "hydra:totalItems": 1,
  "hydra:view": {
    "@id": "/events?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/events?page=1",
    "hydra:next": "/events?page=2",
    "hydra:last": "/events?page=3"
  },

Cursor Pagination

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.

Benefits of Cursor Pagination:

1. 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.

2. 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.

3. Flexibility: Cursors can be used to navigate forwards and backwards in the collection without impacting performance.

How to Use Cursor Pagination:

To use cursor pagination with our API, follow these instructions:

1. 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.

2. 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.

3. 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.

4. 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.

Considerations About Cursor Pagination:

• 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.

Example

  curl -i 'https://api.syntage.com/taxpayers/{taxpayerId}/invoices?page=1&itemsPerPage=10' \
    --header 'Accept: application/ld+json' \
    --header 'X-Api-Key: {apiKey}' \
    --header 'X-Pagination-Style: cursor' \
    --header 'X-Pagination-Enable-Partial: 0'

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!