Pagination

• Offset-based pagination (default) - Navigate using page numbers
• Cursor-based pagination - Navigate using cursor tokens for large datasets

​

Offset-based Pagination

​

Query Parameters

​

Example

curl -i 'https://api.syntage.com/events?page=2&itemsPerPage=50' \
  --header 'Accept: application/ld+json' \
  --header 'X-Api-Key: {apiKey}'

​

Response

{
  "@context": "/contexts/Event",
  "@id": "/events",
  "@type": "hydra:Collection",
  "hydra:totalItems": 150,
  "hydra:member": [
    // ... items on this page
  ],
  "hydra:view": {
    "@id": "/events?page=2",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/events?page=1",
    "hydra:previous": "/events?page=1",
    "hydra:next": "/events?page=3",
    "hydra:last": "/events?page=3"
  }
}

​

Considerations

• Best for smaller datasets - Works well for collections with moderate size
• Page drift - If items are added or removed while paginating, you may see duplicates or miss items
• Performance - For large datasets, consider cursor-based pagination

​

Cursor-based Pagination

​

Benefits

• Better performance - More efficient database queries for large datasets
• Stable results - No duplicates or missed items when data changes during pagination
• Scalable - Performance doesn’t degrade as you paginate deeper into the collection

​

Example

curl -i 'https://api.syntage.com/entities/{entityId}/invoices?itemsPerPage=10' \
  --header 'Accept: application/ld+json' \
  --header 'X-Api-Key: {apiKey}' \
  --header 'X-Pagination-Style: cursor'

​

Considerations

• No total count by default - The hydra:totalItems field is omitted to improve performance. To include it, add the X-Pagination-Enable-Partial: 0 header (this may impact response times for large datasets).
• Count on the first page - With X-Pagination-Enable-Partial: 0, hydra:totalItems counts the items that match the request and its cursor: on a page requested through hydra:next, only the items after the cursor. Request the total on the first page, without a cursor.
• Availability - Cursor pagination is available on most collection endpoints.

​

Bounded count

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

• When the items that match the request are within the limit, the response includes the exact hydra:totalItems.
• When they exceed the limit, the response omits hydra:totalItems. The collection has more items than the limit. To count them, narrow the request with filters, such as an issue date range.
• With cursor pagination, without X-Pagination-Enable-Partial: 0, the header has no effect and the response omits hydra:totalItems.