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.

CriterionCursor / keyset paginationOffset / page pagination
Query shapeGET /v1/orders?cursor=eyJpZCI6MTAwfQ&limit=25GET /v1/orders?offset=50000&limit=25
DB complexityO(1) indexed seek on (created_at, id)O(N), scans and discards 50,000 rows
Insert consistencyNo duplicate or skipped records under writesRows shift on live inserts, causing duplicates
Validator checkPasses ADP-010 and ADP-011Triggers 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 }.