Pagination divides a potentially large result collection into bounded pages returned across multiple requests. It lets consumers retrieve only the portion they need, reducing response volume and avoiding slow responses, server crashes, and unnecessary infrastructure costs. section 9.6.6 section 1.2.3
Treat pagination as a list-operation feature alongside filtering and sorting. Keep pagination parameters optional, use helpful defaults, and expose them as query parameters because they modify the requested resource. section 9.6 section 9.6.6
Bank transactions
GET /accounts/12345/transactions?page=3&size=10&amount=gt:200 returns the third page of ten matching transactions. A cursor request such as GET /accounts/12345/transactions?after=2501&size=25 returns the next 25 transactions after cursor 2501. A useful default might return the first 40 transactions when no pagination parameters are supplied. section 9.6.6
Choose the pagination model according to consumer needs, data behavior, and implementation constraints:
- Use index- or offset-based pagination when consumers must jump directly to a page; it is simpler to implement but becomes less efficient for deep pages. section 13.6.2
- Use cursor-based pagination for large or changing datasets when consumers normally request the next page; opaque cursors avoid page shifts and reduce database work. section 13.6.2 section 13.9
- Avoid using the HTTP Range header for pagination; separate query parameters are common practice and intermediaries may strip Range when it is used outside binary chunks. section 9.6.6
- Keep very large lists out of embedded resource models when they need filtering or pagination; represent them through dedicated operations instead. section 8.7.2
Figure 8.17 We shouldn’t embed lists requiring filtering or pagination.
Use the figure to recognize when a list has outgrown an embedded resource representation and needs dedicated operations. section 8.7.2
Design exercise
For an events endpoint that currently returns every event, cap the response at 50 events and decide whether an optional page parameter is safe. Account for existing consumers before changing the response contract. section 15.13
