JSON API Pagination Patterns
Pagination shapes the ergonomics and performance of your JSON APIs. Choose a strategy that balances simplicity and stability across changing datasets. Below we outline the three common approaches, trade‑offs, and design tips that help clients implement robust pagination.
Offset/Limit
Clients request ?offset=0&limit=20
. It is easy to understand and widely supported by SQL. However, insertions or deletions between requests cause items to shift, producing duplicates or gaps. Offset also grows slower at high values.
Page‑based
Clients request ?page=3&per_page=20
. This is human‑friendly for UIs and SEO, but inherits the same instability and performance concerns as offset. Prefer stable sort keys and clear metadata, such as total pages.
Cursor‑based
Responses include a cursor token (often an encoded last item key). Clients request ?after=eyJpZCI6IjEyMyJ9
. This yields consistent forward/backward iteration and scales well. Cursors should be opaque, signed, and short‑lived.
Response Shape
{ "items": [/* ... */], "page": {"next": "cursor", "prev": null, "perPage": 20} }
Always document ordering guarantees, maximum page size, and how to detect end‑of‑list.