API Pagination, Error Contracts and Safe Retries
Design a predictable list endpoint, distinguish cursors from offsets and specify what clients should do after a timeout.
Key Learning Objectives
- Explain offset versus cursor pagination.
- Return a consistent error object.
- Recognise retry risks for non-idempotent POST.
- Test limits and malformed requests.
Choose pagination for a changing dataset
Offset pagination asks for a position in the list and is simple for small stable result sets. When rows are inserted ahead of the offset, clients may see duplicates or skip rows. Cursor pagination uses an ordering key (often created_at plus ID) to ask for items after a known position. It works best when the ordering is stable and the cursor is opaque to clients. Always define a maximum page size on the server.
Make the response contract predictable
A useful list response includes items and nextCursor, with null indicating no subsequent page. Document consistent 400 errors for invalid limit values and 401/403 responses for access errors. Prefer machine-readable error codes alongside a human-readable message. Validation must happen on the server because a client can send requests that do not use your frontend.
{
"items": [{ "id": "t_10", "title": "Review SQL" }],
"nextCursor": "opaque-next-page-token"
}
A cursor token encodes a continuation point; a client must treat it as opaque and should not construct its own tokens.
Design retries around idempotency
A network timeout does not tell the client whether a server committed the request. Retrying a POST blindly may create a duplicate. For high-impact creates, idempotency keys can let the server recognize repeated attempts. GET is designed to be safe and idempotent; PUT and DELETE are intended to be idempotent in effect, even if repeated responses differ. Make retry behavior part of the API contract and test it.
Build It: Task feed contract review
Design a task list API with paginated responses, validation and retry guidance.
Project Deliverables
- Three sample responses including an error.
- Documented limit bounds and ordering.
- Test cases for inserted records and duplicate POST.
Acceptance Criteria
- Limit above maximum returns a clear 400.
- End of list returns nextCursor null.
- Repeated create with same idempotency key does not duplicate.
Next Steps & Related Learning
This interactive lesson is part of the API Design curriculum. Continue exploring or try another interactive lesson: