21 Pagination

 

This chapter covers

  • How pagination allows users to consume large data sets in bite-sized chunks
  • The specific size of each page of data
  • How API services should indicate that paging is complete
  • How to define the page token format
  • How to page across large chunks of data inside a single resource

In this pattern, we’ll explore how to consume data when the number of resources or the size of a single resource is simply too large for a single API response. Rather than expecting all of the data in a single response interface, we’ll enter a back-and-forth sequence whereby we request a small chunk of data at a time, iterating until there is no more data to consume. This functionality is commonly seen in many web interfaces, where we go to the next page of results, and is equally important for APIs.

21.1 Motivation

21.2 Overview

21.3 Implementation

21.3.1 Page size

21.3.2 Page tokens

21.3.3 Total count

21.3.4 Paging inside resources

21.3.5 Final API definition

21.4 Trade-offs

21.4.1 Bi-directional paging

21.4.2 Arbitrary windows

21.5 Anti-pattern: Offsets and limits

21.6 Exercises

Summary