What is API Pagination?
Pagination turns big archives of data into smaller, more digestible pieces. Clicking through an archive of pictures, or turning the page of a book, are examples of pagination. How is this important in API structure?
When we use a GET API request to request information from a server via API endpoint, there could be thousands of entries in the returned JSON file. The API response sending us thousands of entries at once is a drain of resources and a waste of our time. We want to search through a database a little bit at a time, and paging helps us query databases efficiently.
Pagination Methods
There are a few different methods of API pagination you can use depending on your API's needs.
Offset Pagination
Offset pagination uses the `limit` and `offset` commands already present in the SQL library as query parameters. For example:
`GET /paintings?offset=0&limit=10`
`offset` tells the server the number of items that should be skipped, while `limit` indicates the number of items to be returned. So, this will search ten paintings at a time, and skip 0 of them. One issue with this approach is the outcome if someone removes a record from the data set. This throws off your whole search, and you will miss one item.
Keyset Pagination
Keyset pagination takes a cue from SQL database searching. It passes a query parameter with a timestamp to thoroughly paginate through an API.
- The client requests most recent items with `GET /items?limit=20`
- Upon clicking the next page (first page to second page), the query finds the minimum created date of 2019–01–20T00:00:00 (the first 20 results). This is then used to create a query `limit` filter for the next page:
`GET /items?limit=20&created:lte:2019-01-20T00:00:00`
This will paginate until the last page is reached.
Seek Pagination
Seek pagination returns consistent ordering even when new items are added to the table. We add `after_id` or `start_id` URL parameters.
- Client makes request for most recent items: `GET /items?limit=20`
- Upon clicking the next page, client finds the last id of ‘20’ from previously returned results. and then makes second query using it as the starting id: `GET /items?limit=20&after_id=20`
- Upon clicking the next page, client finds the last id of ‘40’ from previously returned results. and then makes third query using it as the starting id: `GET /items?limit=20&after_id=40`
Designing APIs for Pagination
When building your API, keep pagination in mind. Use common variables like `self`, `first`, `next`, and `last` that are widely used by API developers. More APIs means more GET requests, and when someone requests your data, take care to set it up for them to paginate it.
Frequently Asked Questions
What is API pagination?
API pagination is a technique that breaks a large set of data into smaller, more manageable pieces instead of returning everything at once. It lets an API serve big archives of data in digestible chunks across multiple responses.
Why is pagination important for APIs?
Returning a massive JSON response in one request drains server resources and wastes time. Pagination lets developers retrieve data incrementally, which improves efficiency and the overall user experience.
How does offset pagination work?
Offset pagination uses limit and offset query parameters, such as GET /paintings?offset=0&limit=10. The offset specifies how many items to skip and the limit sets how many items are returned. One drawback is that it can break and miss items when records are deleted between requests.
What is keyset pagination and when should you use it?
Keyset pagination uses values like timestamps as query parameters to navigate through records, for example GET /items?limit=20&created:lte:2019-01-20T00:00:00. It is especially useful for data that is ordered chronologically.
How is seek pagination different from offset pagination?
Seek pagination uses an identifier such as after_id or start_id in the URL, for example GET /items?limit=20&after_id=20. Unlike offset pagination, it keeps a consistent ordering even when new rows are added to the table.
What are some best practices for paginated APIs?
Use standard, well-known variables such as self, first, next, and last across your API. Keeping these consistent makes the API easier for developers to learn and work with.
