APIs: evolving without breaking your integrations

Tell compatible changes from the rest

The rule is simple to state: adding is compatible, removing and renaming are not. What makes it hard to apply are the in-between cases that look harmless.

The third line is the most underestimated: adding a new status to an enum breaks every client that strictly validates the values it receives. It is an addition, and yet it is a break.

Document what is not guaranteed

An API contract must say what can be relied on, but above all what cannot: the order of fields, the exact shape of identifiers, the presence of undocumented fields, the stability of natural-language error messages.

Without that list, every observed detail becomes an implicit guarantee. Integrators rely on what they see, not on what you intended to promise.

Version as little as possible

A new major version doubles the maintenance cost and forces every partner to plan a migration. Reserve it for unavoidable breaks, and prefer adding fields, progressive deprecation and default values.

1. Add the new field next to the old one, removing nothing.
2. Announce the deprecation with a date, in the documentation and in a response header.
3. Measure who still uses the old field, by logging the calls.
4. Warn the last remaining users individually before removal.

Make errors usable

An integration breaks more often on error handling than on the happy path. A stable machine-readable code, a natural-language message for humans, and a correlation identifier to find the call in your logs: those three elements avoid most round trips.

State what is safe to retry as well. A partner who does not know whether their request was taken into account will try again — and create a duplicate if you have not planned an idempotency key.

An API is a promise kept over time. What makes it reliable is not its elegance, but the predictability of its changes.