API Design Basics

A REST-style API names things and acts on them. Paths are nouns, /orders, /orders/123, /orders/123/refunds, and the HTTP method says what you are doing.

Status codes carry more weight than people expect, because clients and infrastructure branch on them.

• 2xx: worked.
• 4xx: the caller is wrong. Do not retry without changing something.
• 5xx: we are wrong. Retrying may work.
• 409 Conflict: the request clashes with current state.
• 429 with Retry-After: slow down, and here is for how long.

Two properties, often confused.

Safe means the call changes nothing. GET and HEAD are safe.

Idempotent means doing it twice has the same effect as doing it once. PUT and DELETE are idempotent by definition: setting a value to X twice leaves X, deleting twice leaves it deleted. GET is both.

POST is neither. Two identical POSTs create two orders. And a client that gets no response cannot tell whether the server processed the request. So the retry it must perform is exactly the thing that creates the duplicate.

Never return an unbounded list. The only question is how you break it up.

The offset failure is worth picturing. A user reads page 1, someone inserts a row at the top, and one item slides past the boundary onto page 2. The user sees it twice, or never sees it. Cursor pagination anchors on a position in the data rather than a count of rows, so inserts elsewhere do not move it.

The options are a path version (/v1/orders), a header, or a query parameter. Path versioning wins on being visible in logs, in browsers, and in support tickets.

The more useful point: most changes need no new version.

• Safe: adding an optional field, adding an endpoint, adding an optional query parameter.
• Breaking: removing a field, renaming one, changing a type, making an optional field required, tightening validation.

So the discipline is: add, never remove. When you must remove, stage it. Ship the new field alongside the old, migrate callers, watch usage of the old one fall to zero, then delete. Versioning is for the change you cannot make additively, and it is expensive because every version is code you maintain forever.