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.
