Every API that lives long enough faces the same tension. The product changes. Customer requirements evolve. Performance work forces backward-incompatible refactors. And on the other side of every one of those changes are integrators — customers, partners, internal teams — who wrote code against last year’s shape of your API and do not plan to rewrite it on your schedule.
API versioning is the discipline of changing what you need to change without unilaterally breaking those integrators. It is less about picking a pattern and more about picking a commitment: how long will we carry old shapes, how loudly will we communicate the end, and how seriously will we enforce the retirement when it arrives?
Three versioning patterns dominate the landscape. None is universally correct. Each fits a different kind of API program.
URI versioning
The version lives in the path. /v1/orders and /v2/orders are distinct URIs that can be served by distinct code paths, cached independently, and routed at the load balancer.
Pros. URI versioning is visible. A developer reading a log or a curl command can see exactly which version is in play. It is cache-friendly — every URL is its own cache key. It is easy to route — a simple prefix match sends traffic to the right implementation. Every client library and HTTP tool on earth handles it without special treatment.
Cons. The version is part of the resource identity, which is philosophically awkward: the same “order 42” appears at two URLs. Going from v1 to v2 requires every integrator to update every endpoint they call. The pattern resists minor versioning — v1.1 and v1.2 in the path are unusual and visually noisy.
When it fits. Public APIs for third-party integrators, where visibility and tooling compatibility matter more than philosophical purity. APIs with infrequent, coarse-grained version changes (years between major versions, not months). Programs where the cost of multiple parallel implementations is acceptable.
Header versioning
The URI stays the same. The client sends a header (X-API-Version: 2026-04-15 or Accept: application/vnd.company.v2+json) to declare which version of the contract it expects.
Pros. Resources have stable identities. Versioning is decoupled from URL structure, which lets you version at finer granularity — per endpoint, per field, per date. Stripe’s date-based versioning is the best-known example: every API request carries a date header, and the server renders the response as it existed on that date. The pattern is powerful because it lets you roll out changes continuously while preserving old behavior for pinned clients.
Cons. Harder to debug. A log line with a URL tells you half the story; you need the headers too. Harder to test ad-hoc — curl requires extra flags, browser debugging is clunky. Caches need to vary on the version header, which is subtle to configure correctly. Integrators who forget to set the header get default behavior that may be dangerous as the default shifts.
When it fits. Internal APIs where the toolchain can enforce header discipline. Sophisticated public APIs where integrators are technical and fine-grained versioning is worth the operational cost. Programs that ship changes continuously and cannot tolerate the “big bang” shape of URI major versions.
Content negotiation
A specific flavor of header versioning that uses the Accept header with a custom media type. The client asks for application/vnd.company.order.v2+json; the server returns that representation or a 406.
Content negotiation is philosophically pure — it is the mechanism the HTTP specification provides for exactly this problem. In practice it shares the debugging and tooling friction of header versioning plus additional complexity. It fits organizations that value alignment with HTTP standards and have the discipline to enforce the pattern. In most practical API programs, the extra cost is not repaid.
The deprecation lifecycle
Picking a versioning pattern is the easy part. The harder discipline is retiring old versions without breaking integrators or losing trust.
A reasonable deprecation lifecycle has five phases.
1. Announce with a sunset date
The moment a new major version ships, the retirement of the old one is announced — with a specific date, not a vague “in the future.” Public APIs typically give integrators twelve to twenty-four months. Internal APIs can be tighter, but the date is still specific.
The announcement goes to every integrator you can reach: the developer portal, the changelog, email to registered developer contacts, and — crucially — in-response signals (more on those in a moment).
2. In-response deprecation signals
From announcement onward, every response from the deprecated version carries explicit signals:
A
Deprecationheader (RFC 9745) with a timestamp or booleanA
Sunsetheader with the retirement dateA
Linkheader pointing to the migration guide
Sophisticated integrators monitor for these headers and raise internal alerts when they appear. The less sophisticated ones at least have the information in front of them whenever a developer reads a response.
3. Dashboards and outreach
Instrument who is still calling the deprecated version. As the sunset date approaches, reach out directly to the top integrators still on the old version. This is the step most programs skip — and it is where most preventable breakage happens. A human conversation costs a few hours and saves a customer escalation.
4. Hard warnings as the date approaches
In the final month, ratchet up the signals. Add a warning banner to the developer portal. Send a final email. Some programs add intentional latency or occasional 5xx responses to force attention — use this tactic sparingly and only with clear communication, because it will break trust if misapplied.
5. Retire: 410 Gone
On the sunset date, the deprecated version returns 410 Gone with a body pointing to the migration guide. Not 404 — the endpoint existed, and the client deserves to know it was retired intentionally. Not 301 redirect — that silently routes old clients to new contracts, which is almost always the wrong thing because the response shape has changed.
The discipline is to execute the retirement on the date. Slipping the date by a month is merciful once; slipping it routinely trains integrators that deprecation announcements are optional. That is the trajectory where no version ever retires and the API program carries four parallel versions in perpetuity.
The cost of parallel versions
Every active version is a commitment. Security patches have to land on all of them. Bug fixes have to be backported. New features occasionally have to be held back from old versions to avoid accidentally introducing new shapes. The on-call rotation debugs issues across all of them.
A rough rule: each parallel major version adds fifteen to twenty-five percent to the maintenance cost of the API program. Two versions is manageable. Three is a strain. Four is evidence that the deprecation discipline has broken down and the program needs a reset.
The honest framing in the design conversation: we can support parallel versions, but the cost is real, and it trades off against feature velocity in the current version. Integrators who understand this are more cooperative about migration schedules than integrators who assume the cost is zero.
A practical default
For a public API program at a mid-market company, a reasonable default looks like this:
URI versioning for the major version (/v1, /v2)
Backward-compatible changes shipped within a major version without ceremony
Breaking changes require a new major version; major versions are infrequent (annual at most)
Deprecation lifecycle of twelve months from announcement to 410
At most two major versions active at any time — the current and the one being retired
Sunset and Deprecation headers on every deprecated response
A public changelog and a migration guide for every major version transition
This is not the only correct answer. A high-frequency, technical-audience API might choose date-based header versioning and carry a wider fleet of supported versions. A small internal API might dispense with formal versioning entirely and rely on coordinated deploys. The right answer depends on the audience, the frequency of change, and the team’s appetite for maintenance cost.
What does not depend on context is the commitment to follow through. The versioning pattern you pick is a promise to your integrators. The deprecation lifecycle is how you keep that promise while continuing to evolve the product. A program that versions thoughtfully and deprecates on schedule builds the kind of trust that compounds into long partnerships. A program that does neither builds a technical debt ledger that eventually dominates the roadmap.
Top comments (0)