Field notes / Pagination

Pagination patterns for public APIs

Desk with laptop and coffee

Offset is simple until it is not

?page=3&size=50 is easy to document and debug. It performs poorly on large tables and shows duplicates if rows shift while a partner pages.

Cursors stabilise moving data

Encode the last seen sort key in an opaque cursor. Partners cannot jump to arbitrary pages, but catalog sync jobs get consistent slices—usually what B2B integrators need.

Always cap page size

Publish a maximum of 100 or 250 and enforce it server-side. Document the default so test suites do not assume 20.

Include total only when cheap

Exact counts on million-row tables hurt. Offer has_more boolean instead unless your DBA signs off on count queries.