API design — pagination, versioning, errors

An API is a promise to people you will never meet. Once someone depends on it, you cannot quietly change it, and every mistake you made on day one you get to carry for years.

Three of those mistakes come up in most API design discussions: how you page through a long list, how you change the shape of a response without breaking anyone, and what you say when something goes wrong.

Pagination. An endpoint that returns "all" of something is a bug waiting for your biggest customer. Always page. A cursor is an opaque string that encodes the sort key of the last row you returned, so the next query is "give me rows after this point", which an index answers directly. Offset paging asks the database to count past everything before it, so it gets slower the further you go. Across a sharded store it gets much worse, because every shard has to produce all those rows for the merge. Make the cursor opaque (base64-encoded, say), so clients treat it as a token instead of building one by hand, and you can change what is inside it later.

Versioning. You will need to change a response shape. There are three ways to survive it. Put the version in the URL path (/v2/orders): ugly, obvious, and by far the easiest to reason about and to route. Put it in a header: cleaner URLs, but harder to test with curl, which matters more than it sounds. Or do not version at all, and only ever make additive changes: new fields are fine, removing or renaming a field is not. That last approach is often the most practical, with a version bump reserved for a genuine break.

Whichever you pick, say the two rules that keep you safe. Adding a field is safe. Removing or renaming one is not. And clients must ignore fields they do not recognise, which you have to document, or client authors will not know to do it.

Errors. Return the right HTTP status, and a body that a machine can act on and a human can read: a stable machine-readable code, a message for the developer, and where relevant which field was wrong. The status code carries the category: 400 you sent something wrong, 401 who are you, 403 I know who you are and no, 404 not here, 409 that conflicts with the current state, 422 the shape was right but the values were not, 429 slow down, 5xx my fault. The part people get wrong is retryability. A client needs to know whether to try again, so 429 and 503 should carry Retry-After, and other 4xx codes mean "do not retry this unchanged".

Idempotency belongs in the API contract, not only in the implementation. Any endpoint that creates something or moves money should accept an Idempotency-Key header, and you should say in the docs how long you remember it. That header is what lets a mobile client on a bad connection retry safely.

Two more that come up. Filtering and sorting should be a small fixed set of allowed fields, not arbitrary user input turned into a query, or you have handed people a way to run expensive scans. And partial responses (letting a client ask for only the fields it needs) save real bandwidth for mobile, at the cost of a caching layer that now has to key on the field list too.