API pagination best practices

Deliver large sets of data efficiently.

Problem statement

APIs often need to power user experiences such as news feeds, timelines, catalogs or search results. The underlying API in these experiences needs to return a potentially unbounded set of data. It is not feasible to return all data in a single response, as it would lead to slow response times and might even exhaust either the server or client's resources.

Success criteria

Pagination directly impacts the APIs performance. Low level metrics such as CPU or memory usage may provide insight into resource utilization. However, such metrics can usually be simplified to ones that are observable by customers, such as availability and latency.

Product requirements

Pagination divides the data into smaller chunks or pages, which allows clients to retrieve results incrementally. At a minimum, all paginated APIs need to provide a way to retrieve the first page of results, and the next page of results given a previous page.

User stories

As an end user, I want to see the first subset of results immediately, so that I don't have to wait for the entire set to load when I don't need them.Functional

The application should consider prefetching and caching remaining results in the background. So as the user scrolls or navigates to subsequent pages, the perceived load time will be less.

Many web frameworks will prefetch links automatically.

Acceptance Criteria:

1. Given the maximum number of results per page is 100 and there are more than 100 records, when all records are requested from the API, then the API responses only contains the first 100 records.
2. Given the maximum number of results per page is 100 and there are more than 100 records, when all records are requested from the API, then the API responses indicates that there are more results.

As an end user, I want to browse the entirety of results, so that I can find what I'm looking for via recognition instead of having to recall its details.Functional

For some use cases such as news feeds or shopping catalogs, the end user isn't trying to find a particular result. For other use cases, the user may have a particular result in mind, but cannot recall enough details to search for it specifically. In either case the API should provide a means for the end user to access the entire data set.

Acceptance Criteria:

• Given a paginated API response indicates that there are more results, when the next page of results is requested from the API, then the API responds with the results starting from the next record.

As an end user, I want to filter and sort results, so that I can quickly find what I'm looking for in the first page of results.Functional

Paginating results means the end user experience will be optimized for the first page of results. Such APIs should also be accompanied by filtering and sorting in order to allow the end user to narrow down the results set.

The default sort order should facilitate the most common use case, typically reverse chronological order using creation date. This allows an API consumer to easily see a newly created record in the first page of results.

See Sorting and Filtering.

As an end user, I want to jump to different pages of results, so that I can browse items out of order.Functional

This user story applies where the application experience contains a page control. This includes data driven applications and search user experiences, but excludes things like feeds and timeline views which are inherently linear experiences.

Paginated responses should contain metadata about the entire results set, including total number of results or pages, and how to nagivate to the next and previous pages, and first and last pages.

As a developer, I want to distinguish between a successful query that returns an empty set of results and an unsuccessful query, so that the development and debugging of success and failure scenarios does not depend on specific test data.Developer Experience

It is semantically incorrect to return a 404 Not Found status code from a paginated API when there are no results. Instead, return an empty set of results with a 200 Success status code.

As an API owner, I want to monitor the response times of paginated results, so that I can tune the default page size and other parameters to optimize the latency of responses.Analytics

If computers had unlimited processing speed, bandwidth and no latency, then there would be no need to paginate responses.

As an application developer, I want to avoid loading unneeded data, so I can minimize my application's bandwidth and memory consumption.Performance

Application's typically display less information per record on a "list" view than the record's "detail" view. APIs can take advantage of this fact by returnning a summarized or partial representation of a resource within paginated responses, and the full representation when retrieving the response via its ID directly.

Explore design patterns

API examples

• GitHub API: Uses cursor-based pagination for retrieving repositories and other resources.
• Twitter API: Implements cursor-based pagination for fetching tweets and user timelines.

Further reading

• http://apistylebook.com/design/topics/collection-pagination

https://microservice-api-patterns.org/

Related topics