Skip to main content
Home
HexagonalGuru

REST APIs That Age Well: Contracts, Versioning and Errors

HexagonalGuru's avatar

HexagonalGuru

REST APIs That Age Well: Contracts, Versioning and Errors

Your API worked perfectly until it got a second consumer. The first was your own SPA: you controlled it, deployed it in lockstep and coordinated any change in five minutes. The second is an integration you built with a partner two years ago. Now every refactor is an archaeological dig: does anyone use this field? What happens if I change this format? Why does the partner say "everything's been failing since Tuesday"?

The difference between an API that works and an API that ages well is the difference between thinking about today's consumer and thinking about the one three years from now. And almost everything that needs doing is cheap — if done from the start. This guide covers contracts, versioning and errors: the three pieces that decide whether your API will be an asset or a millstone.

The Contract Is the API (Not the Code)

An API is a promise: "if you ask for this like so, I'll answer that like so". The code implementing it can change every day; the promise, almost never. Consumers don't depend on your code: they depend on the shape of your requests and responses, your status codes and your errors.

The practical consequence is contract-first design: the contract (OpenAPI, usually) is written before or alongside the code, reviewed like code, and changes are examined with one question in mind: does this break anyone already integrated? If the answer is yes, it isn't a change: it's a negotiation.

Changes That Add and Changes That Break

Safe and breaking changes in a REST API: adding fields or endpoints is safe; renaming or removing fields, changing types or the meaning of errors breaks consumers

The golden rule of compatibility is that there are two lists, and they're worth internalising:

  • Additive changes (almost always safe): adding a new endpoint, adding an optional field to a response, adding an optional parameter with a default value, adding a new enum value only if consumers tolerate unknown values.
  • Destructive changes (they break): renaming or removing a field, changing its type, making an optional parameter mandatory, changing the meaning of a status code, tightening a validation that used to pass.

The subtlest trap is the tolerant consumer: a robust JSON client ignores fields it doesn't know, so adding fields is free. But if your consumers validate the schema strictly, even a new field breaks. Publish your tolerance policy in the docs: "we may add fields without notice; ignore the ones you don't know" is a sentence that prevents years of pain.

Versioning: the Last Resort, Not the First

When a destructive change is unavoidable, it's time to version. But v2 isn't a design decision: it's an operational one that multiplies the work — two contracts to maintain, two test suites, two documentations. Before getting there:

  1. First, the additive. Can you add the new field without removing the old one? New price_cents living alongside old price, with the old one marked deprecated. It's ugly for a while; it's far cheaper than a v2.
  2. Then, the extension. A new endpoint instead of changing the old one? New /v1/invoices/{id}/summary while the old detail stays untouched.
  3. Only then, the version. And when it comes: with a published deprecation date for the old one, a concrete migration guide and direct contact with known consumers. A version without a retirement plan is technical debt with a pretty name.

On the mechanism (path /v1/, Accept header, query param): it matters less than coherence. Pick one, document it and don't change it. The path has the advantage of being visible and easy to route and cache; the header is "purer" but invisible in logs unless you record it.

Errors Are Contract Too

Consumers write code against your errors: they retry, show messages, decide. An error that changes without notice breaks as much logic as a renamed field. The rules that prevent it:

  • Use HTTP codes with their meaning. 400 is invalid request, 401 unauthenticated, 403 no permission, 404 doesn't exist, 409 state conflict, 422 valid format but invalid business, 429 too many requests. A 200 with {"error": "..."} in the body breaks every sensible HTTP client in the world.
  • A single, documented error format. The de facto standard is Problem Details (RFC 9457): a JSON with type, title, status, detail and a stable machine code per error type. The human message may change; the machine code is contract.
  • Idempotency on writes. If a timeout causes a retry of POST /payments, does the customer get charged twice? An Idempotency-Key header that lets the server deduplicate retries turns a network failure into a non-event. It's the piece that prevents the most grief per euro invested.
  • Actionable validation errors. "Invalid request" forces a call to you. {"code": "VALIDATION_ERROR", "fields": {"email": "must be a valid email"}} lets the consumer fix it themselves.

What Keeps an API Young

Beyond the contract, four habits that make the difference at year three:

  1. Pagination from day one. The listing that returns 50 records today will return 50,000 tomorrow. Cursor or page, doesn't matter; what matters is that adding it later changes the response shape, and that breaks.
  2. Contract tests. A suite verifying that responses still honour the published schema, run in CI. Unit tests prove your code; contract tests prove your promise.
  3. Living documentation. Generated from the contract, not hand-written in a wiki that goes stale the first month. If docs and code disagree, the consumer believes the docs — and the bug is yours.
  4. Per-client consumption logs. Knowing who calls what is what lets you decide with data what can be retired. Without consumption telemetry, every deprecation is a leap of faith — and here your observability pays for itself.

Common Mistakes

  1. Designing the API in the image of the database. Exposing tables and joins as resources turns every schema migration into a destructive change. The API models the consumer's domain, not your tables.
  2. The SPA as the only imagined consumer. "Only our web uses it" lasts exactly until the first partner, mobile app or internal integration. Design as if the second consumer already existed.
  3. Versions that never die. Maintaining v1, v2 and v3 at once with no retirement date triples maintenance out of fear of one conversation. Deprecating with a date and notice is cheaper and more professional.
  4. Errors as shapeless exceptions. A stack trace in the 500 body doesn't help the consumer and leaks your internals. The production error is a public document: treat it as one.
  5. Changing the contract without telling anyone. The API changelog is as mandatory as the product's. Every additive change gets announced; every destructive change gets negotiated.

In Short

An API that ages well is a cared-for promise: an explicit, reviewed contract; additive changes before destructive ones; versioning as a last resort with a retirement plan; errors with a stable format and idempotency on writes. Pagination, contract tests and generated documentation keep it young. It's all cheap at the start and very expensive later — and the consumer three years from now will thank you, even if they never know who you are.

If your API has grown without a clear contract and every change is a roulette, we can review it and propose a stabilisation plan without breaking your current consumers. Let's talk →

Keep reading: REST vs GraphQL: how to choose the right API for your project.

  • #apis
  • #rest-api

Related articles

Shall we start?

Ready to build something that grows with your business?

Tell us your goals and together we will map the design, development and technology route that takes you from vision to measurable results.