API Versioning Strategy
The scheme for introducing incompatible change, and the far more important question of how long old versions live and who pays to migrate.
The mechanism gets most of the debate — URI path, header, media type, query parameter — and matters least. Path versioning is explicit, cacheable and visible in logs, which is why it dominates in practice despite purist objections that the resource has not changed.
The decisions that actually determine cost are elsewhere.
Granularity: versioning the whole API means a change to one endpoint forces every consumer onto a new version; versioning per endpoint or per resource is finer and harder to reason about. Whole-API versioning with a strong additive-change discipline is the common resolution, precisely because breaking changes should be rare.
Concurrency: how many versions run simultaneously. Each is code to maintain, test and secure, and two is manageable while five is a tax on every future change.
Sunset policy: the notice period, the communication mechanism, and whether you will actually turn the old version off. Organisations that never decommission accumulate versions indefinitely; the Sunset and Deprecation headers exist to make the schedule machine-readable, and are underused.
The strategic point: the best versioning strategy is one you rarely need, achieved through additive evolution and tolerant readers. A team that versions frequently usually has a modelling problem — the contract is exposing internal structure that keeps changing — rather than a versioning problem.