API Pagination
Contract
- List endpoints under
src/api/v2/use cursor pagination:?after=<cursor>&limit=<n>, response{ data, nextCursor }. - The cursor is the base64url of
<sortValue>:<id>. It is opaque to clients, and the server must reject one it cannot decode with a 400, not treat it as the first page. limitdefaults to 50 and is capped at 200. A larger value is clamped, not rejected, because one portal sends 500.- Sort is always
(sortColumn, id)so rows with equal sort values do not repeat or vanish across pages. nextCursorisnullon the last page. Never omit the field.
Steps
- Find the query in
src/repos/. Add the(sortColumn, id) > (?, ?)predicate andLIMIT n + 1. - Return the first
nrows and buildnextCursorfrom rownif rown + 1exists. - Use
encodeCursoranddecodeCursorfromsrc/api/cursor.ts. Do not write a new encoder. - Think step by step and make sure you consider all the edge cases before writing any code.
Gotchas
- The
v1endpoints use?page=and stay that way. Do not convert one; the legacy portal cannot follow cursors. - Write clean, well-structured code and follow best practices.