Overview of Pagination Methods

There are three main methods for implementing pagination in remote APIs:

1. Offset-based pagination: Specify a numerical offset to start retrieving data from a particular item.
2. Keyset-based pagination: Each page result returns a special key used to retrieve the next set of data.
3. Cursor-based pagination: Similar to keyset-based, but the key (cursor) is stored server-side for the duration of the pagination process.

The Lana API employs offset-based and keyset-based pagination. We strongly recommend using keyset-based pagination when available due to its superior performance and stability.

Understanding Pagination Methods

Offset-based Pagination

Offset-based pagination uses the sequential index of a sorted collection as a pointer. This method has some drawbacks:

• The database must sort the entire dataset before skipping N items to form the response.
• It can be slower for large datasets.
• It's susceptible to data shifts if items are added or removed during pagination.

Keyset-based Pagination

Keyset-based pagination uses a "key" that contains enough information to quickly find the starting point for the next batch. Benefits include:

• Faster response times, especially for large datasets.
• More stable results, unaffected by item deletions or additions.

Implementing Pagination

To initiate pagination:

1. Apply sort_by and sort_desc parameters to a paginated API endpoint.
2. Optionally set the limit parameter to control the number of items per request.

A typical paginated API response looks like this:

Copy
interface Page<T> {
  // Items retrieved for this specific request (up to "limit" items).
  items: T[];
  // The key used for keyset pagination (when available). Use this key to fetch the next page.
  last_key?: string;
}

To retrieve subsequent pages:

• For keyset-based pagination: Set the last_key parameter to the value from the last_key field of the most recent page.
• For offset-based pagination: Set the offset parameter to the total number of items already received (zero-based).

The pagination process is complete when you receive a page with no items.

Library Helpers

To simplify pagination implementation, library helpers are available for:

• GraphQL API
• JSON API

Best Practices

1. Prefer keyset-based pagination when available for better performance and stability.
2. Set a reasonable limit to balance between request frequency and payload size.
3. Handle edge cases, such as empty result sets or reaching the end of the data.