REST APIs in practice: versioning, pagination, errors, and contracts that survive change

Designing a REST API is easy. Designing one you can still change in three years, while other people's software depends on it, is the actual problem. Every field you return is a promise, every status code is a branch in someone else's error handling, and the moment a third party integrates, your internal data model has become a public contract whether you meant it to or not.

This is about the four decisions that determine whether that contract survives: how you version, how you paginate, how you report errors, and how you describe and enforce the whole thing. None of them are hard individually. Getting them wrong is expensive in a way that is hard to reverse.

Most versioning arguments are really disagreements about this question. Get the definition right and you will need to version far less often than you think.

There is a second, harder category: behaviour nobody documented but clients depend on anyway. Result ordering you never promised. A field that has always happened to be non-null. Timing that was always fast. This is Hyrum's Law - with enough consumers, every observable behaviour of your system becomes something somebody relies on. You cannot prevent it; you can only reduce the surface by documenting what is guaranteed and deliberately varying what is not.

Before any of the four topics, the basics have to be right, because everything else compounds on them.

GET, PUT and DELETE are idempotent by definition. POST is not, which is a problem the moment a client retries a payment after a timeout. The standard solution is a client-supplied key.

Error design is where APIs most often fail their consumers, and it is the cheapest of the four to get right, because there is a standard for it.

The type URI is the machine-readable identifier and the part that matters most. Clients branch on it, not on the human-readable title, which means you can rewrite your error prose for clarity without breaking anyone. Make the URI resolve to a page explaining the error and how to fix it - that page is documentation you only write once.

Every collection endpoint needs pagination from day one, including the ones you are sure will stay small. Retrofitting it is a breaking change, because clients that received everything now silently receive the first page.

The correctness argument is stronger than the performance one. With offset pagination on a collection sorted newest-first, a row inserted between requests pushes everything down by one - so the client sees an item twice and misses another entirely. For an export or a sync job that is silent data corruption.

For very large exports, offer a different mechanism entirely rather than expecting clients to walk ten thousand pages: a bulk export job that returns a download URL, or a sync endpoint that accepts a since watermark.

The most-argued and least-important of the four, in the sense that any of the common approaches works if your change discipline is good, and none of them saves you if it is not.

Recommendation: major version in the URL path, additive changes within it. /v1 changes only in backward-compatible ways; anything breaking waits for /v2. This is understandable to everyone, easy to route at the edge, and does not require your consumers to learn anything.

There are standard headers for this, and almost nobody uses them. Deprecation (RFC 9745) says the resource is deprecated and optionally when that took effect. Sunset (RFC 8594) says when it stops working. Together they let a client detect the problem automatically rather than reading a blog post.

A contract that only exists in prose is not a contract. It has to be machine-readable, and something has to fail when the implementation drifts from it.

Spec-first or code-first is a genuine trade rather than a settled question. Writing the spec first forces design discussion before implementation and makes the contract the artifact everyone reviews. Generating it from typed code - FastAPI, Hono with zod-openapi, tRPC-adjacent tooling - guarantees the spec matches reality, which is the failure mode that actually hurts.

Pick based on which failure you fear more: a spec nobody implements, or an implementation nobody designed. If you generate, the schemas that validate incoming requests must be the same ones that produce the spec, or you have reintroduced the drift you were avoiding.

Consumer-driven contract testing - Pact and its equivalents - has each consumer declare what it needs, and the provider verifies it can satisfy every declared expectation. This catches the case an integration test cannot: a change that is fine for the consumers you tested and breaks one you forgot about.

The four decisions in the title are really one decision made four times: how much room are you leaving yourself to change your mind? An envelope instead of a bare array. A cursor instead of an offset. A type URI instead of a message string. A generated spec instead of a document. Each one costs almost nothing up front and buys you a change you can make later without a migration.

The versioning strategy matters less than most teams think, because the goal is to need it rarely. Additive change, tolerant readers and response types you control will carry an API for years inside /v1. When you do need /v2, the Deprecation and Sunset headers exist so that consumers find out from your API rather than from a failure.

If you do three things from this: put oasdiff breaking in CI so the build fails before your consumers do, adopt RFC 9457 problem details so errors are machine-readable from day one, and paginate every collection with a cursor and an envelope. The rest is convention, and convention is only worth having if it is enforced.