Note: This is a part of our series on API Pagination where we solve common developer queries in detail with common examples and code snippets. Please read the full guide here where we discuss page size, error handling, pagination stability, caching strategies and more.
There are several common API pagination techniques that developers employ to implement efficient data retrieval. Here are a few useful ones you must know:
1. Offset and Limit Pagination
This technique involves using two parameters: "offset" and "limit." The "offset" parameter determines the starting point or position in the dataset, while the "limit" parameter specifies the maximum number of records to include on each page.
For example, an API request could include parameters like "offset=0" and "limit=10" to retrieve the first 10 records.
GET /aCpi/posts?offset=0&limit=10
2. Cursor-Based Pagination
Instead of relying on numeric offsets, cursor-based pagination uses a unique identifier or token to mark the position in the dataset. The API consumer includes the cursor value in subsequent requests to fetch the next page of data.
This approach ensures stability when new data is added or existing data is modified. The cursor can be based on various criteria, such as a timestamp, a primary key, or an encoded representation of the record.
For example - GET /api/posts?cursor=eyJpZCI6MX0
In the above API request, the cursor value `eyJpZCI6MX0` represents the identifier of the last fetched record. This request retrieves the next page of posts after that specific cursor.
3. Page-Based Pagination
Page-based pagination involves using a "page" parameter to specify the desired page number. The API consumer requests a specific page of data, and the API responds with the corresponding page, typically along with metadata such as the total number of pages or total record count.
This technique simplifies navigation and is often combined with other parameters like "limit" to determine the number of records per page.
For example - GET /api/posts?page=2&limit=20
In this API request, we are requesting the second page, where each page contains 20 posts.
4. Time-Based Pagination
In scenarios where data has a temporal aspect, time-based pagination can be useful. It involves using time-related parameters, such as "start_time" and "end_time", to specify a time range for retrieving data.
This technique enables fetching data in chronological or reverse-chronological order, allowing for efficient retrieval of recent or historical data.
For example - GET/api/events?start_time=2023-01-01T00:00:00Z&end_time=2023-01-31T23:59:59Z
Here, this request fetches events that occurred between January 1, 2023, and January 31, 2023, based on their timestamp.
5. Keyset Pagination
Keyset pagination relies on sorting and using a unique attribute or key in the dataset to determine the starting point for retrieving the next page.
For example, if the data is sorted by a timestamp or an identifier, the API consumer includes the last seen timestamp or identifier as a parameter to fetch the next set of records. This technique ensures efficient retrieval of subsequent pages without duplication or missing records.
To further simplify this, consider an API request GET /api/products?last_key=XYZ123. Here, XYZ123 represents the last seen key or identifier. The request retrieves the next set of products after the one with the key XYZ123.
Also read: 7 ways to handle common errors and invalid requests in API pagination
