API Pagination

A reading-list collection might contain five items today and fifty thousand a year later. Returning everything makes response time, memory use, and network cost grow with the customer's data. Pagination divides a collection traversal into bounded requests, but the boundary between requests introduces questions that a single response never had to answer.

A useful pagination contract tells clients how to request a page, continue, recognize completion, and recover when data changes or a request fails.

This chapter develops that contract for a fictional bookstore API that uses HTTPS.