API Pagination

Last Updated Aug 06, 2021

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 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.