One field, renamed
Before a Tuesday release, a food lookup on the nutrition API returned {"name": "Greek yogurt, plain", "kcal": 97, "protein_g": 9}. After it, the same lookup returned {"name": "Greek yogurt, plain", "energy_kcal": 97, "energy_kj": 406, "protein_g": 9}.
The rename lined kcal up with the new energy_kj, and every test passed, because every test was the API team's own. Within an hour two partner apps broke, differently. A diet app's iOS build from last year decoded each food into a type where kcal was required; with the key gone, decoding failed and search showed Something went wrong for every food. A fitness app's older Android build read kcal with a default of zero, so it kept working and logged every meal as zero calories. The release was rolled back that afternoon. The meals already logged stayed wrong.
Partners' users do not update on anyone's schedule: a build shipped today can still be calling you 18 months from now, and you cannot force an update. Once a second team, a mobile app or a paying customer calls an endpoint, its shape stops being yours to change alone. So the question is never whether to version. It is which changes need a version at all, and how to retire an old one without an outage in someone else's app.
An API has a wire contract: its fields, types, status codes and what they mean. It also has a surface, the URL and headers a client calls. Most evolution should extend the contract compatibly, without touching the surface; a new version is the expensive, last-resort tool for changes that cannot be made compatible.
Additive or breaking
The rename was two changes in one release: an addition (energy_kcal, energy_kj) and a removal (kcal). Most of the job is sorting changes into piles:
- Additive changes usually need no version: a new optional field, a new endpoint, a new optional query parameter. A new enum value belongs here only for clients that tolerate values they do not know.
- Breaking changes are what versions exist for: renaming or removing a field, changing a type (
97becoming"97"), tightening validation, changing what a status code means. - Breaking changes that look additive: making an optional field required, narrowing an enum, changing a default value. Nothing was removed, and old callers still break.
Additions stay safe because of a rule on the client side: a tolerant reader ignores fields it does not know and never fails on them. Ask partners for it, and do not rely on it. Swift's standard decoding ignores unknown keys, but Kotlin's kotlinx.serialization rejects them by default, so on some partner's Android build even a new field fails the whole parse. A client that decodes a string into a fixed enum fails on the value it has never seen. And tolerance only covers what was added: the fitness app tolerated the missing kcal perfectly, which is how it logged zeros.
Neither app had failed on the two new fields, so the fix was not a v2. It was to keep kcal and send energy_kcal beside it, the same number under two names, with kcal marked deprecated: still sent and documented, but flagged as not for new integrations. A new field alongside the old one covers most of what a rename was for, the way amount_cents can sit next to a legacy float amount.
kcal, and the rename would have failed before deploying, and only for the callers who really depend on that field.Where the version goes
Some changes cannot be made side by side. Two years on, the food response carries six deprecated fields next to their replacements, and the team wants nutrients as a list with units instead of forty flat fields. An old client cannot read that structure, and sending both shapes would double every response. That needs an explicit version, and the version needs a place to live:
- URL versioning (
/v2/foods/5000159407236) is visible, cacheable and easy to route at a gateway. - Header versioning (
Accept: application/vnd.nutrition.v2+json) keeps URLs stable, but the version is absent from the URL, so shared links cannot carry it, and default access logs and URL-keyed caches miss it unless you log the header and sendVary: Accept. - Date-based versions (
Stripe-Version: 2024-06-01) pin a consumer to the behaviour of a given day; one way to serve them is a chain of small transforms from the newest shape back to each older date. Good when you ship many small breaking changes; heavy to maintain otherwise.
Pick one, and pick the URL if in doubt: the boring choice, visible in every log line you already have. A v1 in the URL with no rule for what triggers v2 adds nothing, though, because every breaking change still lands in v1. Version the contract, and only when a change cannot be additive.
Two shapes, one implementation
A v1/ and a v2/ copy of the foods service would double every bug fix as the copies drift. The pattern that scales is translation at the edge: the foods service implements v2 only, and a small adapter in the gateway rewrites each v1 request into v2 and each v2 response back into the v1 shape, flat fields and old names included. The gateway itself has its own article, API gateway & the edge; when each client already has its own backend, the adapter can live there instead, as in The BFF tier: gateway, sessions & fan-out.
Both v1 apps keep calling the paths they were built for; the gateway's adapter reshapes their requests and responses, so the foods service speaks only the current contract.
When the last v1 caller is gone, you delete one adapter, not a branch in every service. The limit: v1 must be expressible from v2, so a v1 field that v2 dropped entirely has to be computed by the adapter or kept in the service, and a v1 behaviour that v2 changed, such as looser validation, cannot be rebuilt by reshaping JSON: the service has to keep it too. When v2 is served by a new system rather than the old one, routing by version moves traffic across piece by piece; read Strangler Fig for that migration.
Neighbours with the same question: Schema evolution: event formats & compatibility for events, Schema migrations without downtime for the column behind kcal, and API styles: REST vs GraphQL vs gRPC for GraphQL and gRPC, which usually add and deprecate fields in one schema rather than mint versions.
To practise the edge, open the API Gateway Patterns Challenge and put the v1 translation in the gateway: route v1 and v2 traffic with Gateway Routing, label the old-client and new-client edges with their versions, and check that every backing service shows a single shape.
Who is still on v1?
A version you cannot delete is a version you pay for forever, so retirement starts the day v2 ships. Announce a date. Return the Deprecation and Sunset headers on every v1 response: the first marks the version as deprecated, the second gives the date it stops answering, and both reach any partner tool or log that records response headers. Measure who still calls, per consumer, at the gateway: each partner app has its own API key, and its app version is in the user agent. Then chase the stragglers by name; shutting off a version you only think is unused is how you find the integration somebody scripted against it years ago. A 12-month window is common for public APIs; internal ones can move in weeks when you own both sides.
Nine months in, v1 is still 7% of food lookups, almost all from one partner's two-year-old iOS build, on phones whose owners never update. What the partner can ship is a minimum-version check: at start-up the app asks the API, on an endpoint that outlives every version, for the oldest supported build and, below it, shows Please update instead of failing at random. The check only helps builds that already contain it, which is why it belongs in a mobile client from its first release. A few weeks before the end, the gateway runs brown-outs: v1 fails for an hour at announced times, so whoever still calls it notices while there is time to act.
On the sunset date the gateway stops translating, and a v1 request gets 410 Gone with a short body naming the replacement, rather than a 404 that looks like a typo or a timeout that looks like an outage: phones with the version check show Please update, and the two-year-old build shows whatever its error handling makes of a 410, which is why the brown-outs came first. Then the team deletes the v1 adapter in one deploy, and with it the last place the old kcal field lived.