API Versioning Is a Promise You Can't Take Back

The first version of an API is the easiest one to ship. There are no existing callers, no compatibility guarantees, no one filing a ticket because a field changed type. That freedom disappears the moment the first external client goes live — and most teams don’t notice it’s gone until they need to change something.

The commitment nobody signs

An API version isn’t just an implementation detail; it’s a contract. Once a partner’s billing job, a mobile app’s login flow, or a third-party integration depends on a response shape, that shape is load-bearing whether or not anyone documented it that way. Renaming a field, tightening a validation rule, or changing a default value can break a caller you’ve never spoken to and don’t know exists.

This is why “just deprecate it” is harder in practice than in a design doc. Deprecation requires knowing who’s still calling the old version, having a channel to reach them, and having enough leverage to make them move. Internal services can be forced to upgrade. External integrators can’t — they upgrade when it’s worth their time, and until then, the old version has to keep working.

Versioning schemes don’t solve the problem, they relocate it

URL versioning (/v1/, /v2/), header-based versioning, and additive-only schema evolution are all ways of managing the same underlying cost, not eliminating it. Each approach trades off differently:

• URL versioning makes breaking changes explicit and routable, but tempts teams to fork logic across versions until /v1/ and /v2/ are maintained as two different products.
• Header or content-negotiation versioning keeps the URL stable, which is friendlier to caching and tooling, but makes it easier for a version to go unnoticed by clients who never set the header and silently get whatever is default.
• Additive-only evolution — never remove a field, never change a type, only add — avoids breaking changes at the cost of an API that accumulates cruft indefinitely, with old fields nobody re-checks before removing them anyway.

None of these choices makes the underlying tradeoff go away. They just decide where the pain shows up: in your codebase, in your clients’ error logs, or in a schema that never gets smaller.

The real fix is upstream of the API

Teams that manage this well tend to invest less in clever versioning schemes and more in reducing how often they need to make breaking changes at all. That means designing response shapes that can absorb new fields without a version bump, treating “this field might not exist yet” as a normal state clients handle from day one, and being deliberate about what gets exposed publicly versus what stays an internal implementation detail that’s free to change.

It also means treating a public API surface as a separate design problem from the internal service behind it. Internal models can — and should — evolve quickly as understanding of the domain improves. The public contract built on top of them needs a translation layer, so refactoring the internals doesn’t force a version bump on every consumer.

Sunsetting is a project, not a flag flip

Even with careful design, old versions eventually need to go. That takes usage telemetry to know who’s still on them, a real deadline communicated well in advance, and — for anything with paying customers on the other end — a migration path that’s easier than staying put. Teams that skip this step end up running three API versions in parallel indefinitely, each one a little more expensive to reason about than the last, because nobody wanted to do the unglamorous work of getting the last few callers to move.

Versioning strategy is a technical decision. Whether you can afford to retire a version is a relationship one.