Versioning: What a Version Even Promises

Strip the debates away and a version is one thing: a named scope inside which the provider promises not to break consumers. Everything else — where the number lives, how requests are routed to it — is mechanism. That is why "should we version?" is the wrong first question. The first question is "which changes will we make without a new version, and which never inside one?" — the Backward Compatibility: The Real Rules line. An API with no written line has no versioning policy, whatever its URLs say.

The strategies differ in *granularity* and *visibility*. A URI version (/v2/users) versions the whole API at once and is visible in every log, cache key and bookmark. A media-type or header version (Accept: application/vnd.acme.v2+json) keeps URLs stable but hides the version from anything that only sees the URL. Date-based pinning (Stripe's model: each account is pinned to the API as it looked on a date, upgraded explicitly) versions *behavior* at per-consumer granularity, which is the gentlest for consumers and by far the most machinery for the provider — every old behavior becomes a transformation layer the provider maintains.

The fourth strategy is the one every healthy API uses most: no new version at all. Additive evolution — new optional fields, new endpoints, new enum values under a documented open-enum rule — extends the contract without invalidating any old clause. Version numbers are for the changes additive evolution cannot absorb. An API that mints versions for additive changes is spending its most expensive currency on things that were free.

Minting a version looks like a routing decision; it is actually a product decision. Every live version needs tests, docs, security patches, on-call engineers who remember its quirks, and capacity. The moment v2 ships, you are not "on v2" — you are operating v1 *and* v2 for as long as v1 has consumers that matter, and Public vs Internal APIs says that is measured in years for a public API. Stripe still serves account versions from the early 2010s; that is not an accident, it is the bill for per-consumer pinning, paid deliberately.

This is why version count is a liability metric, not a maturity signal. A team that reaches /v7/ in three years has usually never defined its breaking-change line: each version was minted in a panic, consumers learned that versions are cheap and ignorable, and now no single version has enough consumers migrated to be retired. The opposite pathology is the API stuck on /v1/ shipping silent breaking changes "because v2 is a big project" — a version label that promises nothing.

The working policy that falls out: keep one live major version per surface, absorb every change the safe list allows additively, and treat a new version as what it is — a migration program you are asking every consumer to fund. Before minting, three questions: can this change be expressed additively (a new field beside the old, a new endpoint beside the old — see Removing Fields Without Removing Consumers and API Migration: Running the Change End to End)? Is the break confined to one resource, so a resource-scoped revision beats a whole-API version? And is the consumer set small and reachable enough that a coordinated migration beats versioned coexistence entirely?

Note what "version" does *not* promise: it does not make breaking changes safe, it makes them routable. Old clients still have to move eventually; the version only controls when and under whose deadline. Teams that treat /v2/ as the fix for a broken v1 discover that the hard part — moving consumers — has not started yet.