api-pagination-designlisted

# API pagination design Any list endpoint that can grow needs pagination, and the choice between cursor and offset determines whether it stays correct as data changes. Offset pagination is simple and wrong under concurrent modification; cursor pagination is slightly more work and stable, which is why serious APIs use it. ## Method 1. **Default to cursor pagination for stability.** A cursor encodes "where the last page ended" (an opaque token over the sort key); the next page continues from there, so inserts and deletes between page fetches do not duplicate or skip items. Offset pagination (`LIMIT 20 OFFSET 40`) skips or repeats items when rows shift under it (a new item at the top pushes everything down a slot): the classic "I saw the same item twice while scrolling" bug (see the connections pattern in graphql-schema- design). 2. **Base cursors on a stable, unique sort.** The cursor must encode a total ordering (a unique column, or a composite like `(created_at, id)` to break ties): sorting by a non-unique column alone makes the cursor ambiguous at boundaries. The sort must be stable across requests (see indexing-strategy: the sort column wants an index, or every page is a scan). 3. **Set and enforce page-size limits.** A default page size and a maximum (reject or clamp larger requests): so a client cannot request a million items in one call and exhaust the server (see backpressure, request-validation). The client as