October 5, 2023

Cursor-based Pagination for All API Endpoints!

We're excited to announce an enhancement to the pagination system for all Lithic API endpoints: Cursor-based Pagination!

What's Changing?

Previously, our top-level API resources like accounts, cards, and transactions employed an offset-based pagination method. By specifying the page and page_size parameters, you could retrieve data. A typical response would appear as:

{
  "data": [...],
  "page": 1,
  "total_entries": 100,
  "total_pages": 10
}

Acknowledging the need for a more efficient and flexible pagination system, especially for large datasets, we introduce the Cursor-based Pagination!

Introducing Cursor-based Pagination!

Cursor-based pagination is now available for all our top-level API resources. This new approach allows you to efficiently retrieve a list of items like events, disputes, and settlement records in reverse chronological order.

Use parameters like page_size, starting_after, and ending_before. If neither starting_after nor ending_before is provided, the API will return the newest objects on the first page in chronologically descending order. Use starting_after to fetch older items after a specific item, or ending_before to get newer items before a certain item. Note that items within a page will always appear in reverse chronological order, and only one of starting_after or ending_before can be specified at a time.

The new response structure is:

{  
  "data": [...],  
  "has_more": true  
}

Why Make the Switch?

Cursor-based pagination offers:

1. Speed: Lower latency, especially for large datasets.
2. Consistency: Fetching data remains consistent even if new data is added.
3. Flexibility: Easily traverse your dataset forwards or backwards based on specific items.

Transitioning from Offset-based to Cursor-based Pagination:

For backwards compatibility, existing customers will have offset-based fields in their response.

If you're using offset-based pagination and wish to migrate:

1. Include the header X-Lithic-Pagination: cursor in your API requests. This will send back cursor-based fields.
2. Contact Lithic Support if you want to set cursor-based pagination as the default for all your endpoints.

All Lithic client libraries will now use cursor-based pagination by default. We advise you to update your libraries to the latest version to leverage this enhancement.

Although offset-based pagination will still be supported for the foreseeable future, we strongly encourage the migration to the new system for its manifold benefits.

Thank you for being a valued part of the Lithics community. We remain committed to enhancing our platform for your benefit. For detailed guidelines on using cursor-based pagination, please refer to our official documentation.