The moment your API stops being internal-only, versioning stops being optional. A public API is a contract hundreds of developers build against, and the first time you break it, you will spend a week on support tickets and lose trust you cannot rebuild quickly. The uncomfortable truth is that there is no single correct versioning strategy; there is only the least painful one for your release cadence, your consumer base, and your team's discipline. This guide walks through the real trade-offs so you can pick one and defend the choice.
Start With a Version in the URL, and Do Not Apologize
URI versioning (https://api.example.com/v2/users) is the most boring, most transparent option, and that is exactly why it usually wins. Every request, log entry, cache key, and documentation page shows the version with zero ambiguity. A developer debugging a live incident can read the path and know immediately which contract is in play. Tools like Swagger UI and API gateways understand it without configuration. It is also trivially cacheable because the URL changes with the version.
The main knock against URI versioning is that it can feel inelegant and occasionally leads to duplicated code paths, because you sometimes need to maintain two controllers for one resource. But duplicated clarity beats clever compression. When you are deciding, ask who consumes the API: if third parties and mobile clients are involved, URI versioning is almost always the safe default. For a deeper look at the design choices that feed into your versioning decision, the API design best practices guide covers naming, errors, and contracts that sit underneath it.
Header and Query Versioning: Cleaner URLs, Hidden Complexity
The alternative to URI versioning is moving the version out of the path. Header versioning (Accept: application/vnd.example.v2+json) keeps URLs stable and reads like a content negotiation problem, which is technically correct. The downside: the version is invisible to caching layers, analytics, and anyone looking at a browser address bar, and it is easy for a client to silently fail to send the header and get the default-which you must define carefully.
Query-based versioning (?version=2) is simpler but leaks into caching keys and pollutes analytics and is easy to forget. Both approaches are workable when you control all consumers, but they create a coordination tax that public APIs rarely want. If you are early in the decision and your consumers are external, bias strongly toward the URL path.
Additive Evolution Before You Ever Cut a v2
Versioning is a last resort, not a ritual. A large share of supposed breaking changes can survive as additive evolution: new fields appended to a response, new optional parameters, new endpoints, or new enum values. Adding a field is backward compatible because old clients simply ignore it. Adding an optional query parameter changes nothing for clients that omit it as long as the default matches prior behavior. This is the cheapest upgrade path in the industry, and teams that practice it rarely need a major version more than once every couple of years.
The discipline required is real. You must resist the urge to clean up an awkward field name by renaming it, because renaming is a breaking change. You must document that unknown fields will be ignored, and then actually ignore them. And you must keep flagging newly optional things as optional so the contract stays honest. The REST API conventions for 2026 spend a good chunk of their attention on exactly how to grow a contract without breaking it.
When the Breaking Change Is Unavoidable
Sometimes you cannot add a field because the new behavior is genuinely different, not just bigger. This is when a major version earns its name. The practices that make a hard cut survivable are mostly about communication and overlap. Announce deprecation no less than six months out for a public API, run the old and new versions side by side, and keep the deprecated endpoint live until you can measure that real traffic has dropped near zero.
Deprecation notices belong in the response itself, not buried in a changelog. A standard way to do this is a Deprecation header with an expiry date, plus a retirement endpoint that returns structured metadata about which versions are active. Consumers who stay quiet will not read your blog; they will read the header on the request they already make. Design the notice into the protocol and your migration rate will be dramatically better than relying on announcement emails.
Handling Multiple Concurrent Versions in Code
The engineering cost of versioning is mostly the cost of running two contracts. You can minimize the pain by versioning at the transport layer with a routing layer that maps a versioned path to an internal handler, rather than forking an entire codebase per version. Many teams use a strategy of "one serializer per version" where the business logic stays shared and only the response shaping differs.
Beware the trap of multiplying endpoints forever. Every major version you actively maintain multiplies your test surface, your documentation, and your bug surface. A healthy public API supports at most two or three active major versions at once, with the oldest on a documented end-of-life date. If you find yourself maintaining four versions, the cost is a signal that your additive evolution discipline broke down somewhere. A well-structured evolution model, as described in the API development guide, keeps the version count low by making growth non-breaking. Pairing a versioning policy with a clean interface is exactly the alignment explored in the API integration guide, where contract stability meets consuming clients.
Backward Compatibility for Mobile Clients Is Different
Mobile apps cannot hot-update at will. A user on an old app version may be running client code written a year ago, and you cannot force them to update on the same schedule you cut releases. This changes your versioning calculus: you must support the oldest app version you still care about, and you need telemetry on the distribution of client versions before you can safely deprecate anything. If 12 percent of your traffic still comes from a two-year-old app, you cannot turn that version off without a plan.
In practice this means mobile-heavy APIs lean even harder on additive evolution and keep the effective major-version window longer. It also means your release notes should clearly flag "requires app 6.2+" so product teams can align app store submissions with backend retirement.
Locking In Your Strategy
Once you pick a versioning scheme, make it a policy, not a preference, and bake it into code review automation. A CI check can reject any new route that does not carry a version prefix or that removes a field from a published schema. OpenAPI tools can diff versions and flag breaking changes before they merge. Here is a snapshot of tools that make versioning and contract control runnable in CI.
| Platform / Tool | Key Features | Pricing |
|---|---|---|
| OpenAPI Diff | Detects breaking changes between OpenAPI specs in CI | Open source and free |
| Stoplight Spectral | Custom lint rules, style and contract validation | Free CLI; paid platform tiers |
| Redocly | Versioned docs rendering, multiple spec support | Free core; commercial tiers |
| Postman | Versioned collections, mock servers, API governance | Free tier; plans from ~$14/user/month |
| Gravitee.io | API gateway with policy-based version routing | Open-source core; enterprise pricing |
Whatever you choose, remember that versioning is a communication problem as much as a code problem. A documented, enforced, and honestly-communicated version policy turns an existential risk into a routine release. This communication-first discipline that keeps version cutovers smooth also keeps time-sensitive real-time systems reliable, which is why the aligns with that operational rigor. Teams that treat contract changes with the same ceremony as a public statement find that consumers migrate faster, incidents drop, and the API itself becomes something other teams recommend instead of tolerate.
Versioning FAQ
For more, check out: .
Is a major version bump required every time I add a required field?
No. Adding a required field on request is a breaking change, but you can usually avoid it by doing a multi-phase rollout: add the field as optional first, then make it required in a later release once all clients send it. True major versions are for changes you cannot make backward compatible, not for every field you forgot.
Should the version live in the URL, a header, or the query string?
For public APIs, URI versioning (/v2/...) is the safest default because it is visible in logs, caches, and documentation and needs no client coordination. Header versioning is workable when you control all consumers, and query versioning is generally discouraged because it leaks into cache keys and analytics. Choose visibility over elegance.
How long should I keep a deprecated version alive?
For a public API, a concrete end-of-life of at least six to twelve months is a good baseline, and you extend it if real traffic remains nonzero. Emit a Deprecation header with the expiry date on every request to the old version so silent consumers see it without reading your blog. Go live only when measured traffic has dropped near zero.
Can I support three major versions at once without chaos?
Technically yes, but you should treat it as an emergency state rather than a goal. Every concurrent major version multiplies your test, documentation, and bug surface. If you regularly hold more than two, your additive-evolution discipline has slipped; tighten the rules on adding fields and deprecating cleanly to collapse the count.
Does GraphQL ever need versioning like REST does?
GraphQL typically avoids URL versions and instead uses additive evolution plus the @deprecated directive, because a typed schema with deprecation metadata lets tools and clients see the sunset without a v2 of the endpoint. The principle is the same as REST evolution: never remove abruptly, deprecate loudly, and give consumers time.