Pagination, filtering, and sorting
O(1) keyset cursors and bounded page sizes enforced by ADP-010 and ADP-011.
Cursor vs offset pagination
How database cost and concurrent write stability compare.
| Criterion | Cursor / keyset pagination | Offset / page pagination |
|---|---|---|
| Query shape | GET /v1/orders?cursor=eyJpZCI6MTAwfQ&limit=25 | GET /v1/orders?offset=50000&limit=25 |
| DB complexity | O(1) indexed seek on (created_at, id) | O(N), scans and discards 50,000 rows |
| Insert consistency | No duplicate or skipped records under writes | Rows shift on live inserts, causing duplicates |
| Validator check | Passes ADP-010 and ADP-011 | Triggers ADP-011 warning when cursor is absent |
Bound page sizes and collection envelopes
Set minimum: 1, maximum: 100, and default: 25 on limit, and wrap responses in an extensible envelope: { "data": [...], "next_cursor": "...", "has_more": true }.