API Versioning Strategies: URI, Header, and Content Negotiation

Every API eventually needs to change in a way that breaks existing clients. A field gets renamed, a response shape gets restructured, an endpoint gets split into two — and somewhere out there, a consumer's code that you don't control and can't see is calling your API right now, expecting the old contract. Versioning is how you make that change without waking up to a queue of angry support tickets.

"Just don't break anything" sounds like a strategy until you've maintained a public API for more than a year. Business requirements change, data models evolve, and security or performance fixes sometimes require incompatible changes. Once you have external consumers you don't control — partners, third-party developers, mobile apps you can't force-update — you need an explicit, published mechanism for introducing breaking changes without breaking everyone at once. That's what versioning strategy actually solves: not preventing change, but giving consumers a safe, predictable path through it.

URI versioning: simple, visible, and the most common

URI versioning puts the version number directly in the path, e.g. https://api.example.com/v1/users or https://api.example.com/v2/users. It's by far the most widely adopted approach among public APIs — Stripe, GitHub, and countless others use some variant of it — because it's the easiest to understand, test, and operate.

The advantages are practical rather than theoretical. The version is explicit and impossible to miss: a developer reading the URL in a browser, a log line, or a support ticket immediately knows which contract is in play. It's trivially cacheable, since /v1/users and /v2/users are distinct cache keys with no Vary header gymnastics required. And it's easy to route at the infrastructure layer — a gateway or load balancer can send /v1/* traffic to one set of services and /v2/* to another without inspecting request bodies or headers.

The downside is more philosophical, but it has real consequences. Under REST's resource-oriented view, a URI is supposed to identify a resource, not a version of a representation of that resource — /v1/users/42 and /v2/users/42 arguably describe the same underlying user, yet they're treated as entirely separate URIs. That purity argument rarely stops teams from shipping URI versioning anyway, but it does have a practical side effect: every version bump duplicates routes, controllers, and often documentation, and consumers have to physically rewrite URLs to migrate rather than just changing a request header.

URI versioning is putting the model year on the license plate instead of the car — it works, everyone can read it, but now you're maintaining a fleet.

Header versioning: cleaner URIs, less discoverable

The alternative is to keep the URI stable and put the version somewhere in the request headers instead. There are two common flavors. The first is a custom header such as API-Version: 2 or X-API-Version: 2, which the server reads to decide how to process the request and shape the response. The second is Accept header content negotiation, where the version is embedded in a custom media type, e.g. Accept: application/vnd.company.v2+json.

Header versioning keeps your URI space clean — one canonical /users endpoint, one resource identity, no route duplication. It also decouples the resource's identity from its representation, which lines up more closely with REST theory than URI versioning does.

In practice, though, it trades discoverability for elegance. You can't version-switch by editing a URL in a browser address bar; you need a tool like curl, Postman, or actual client code to set headers. It's less obvious to developers skimming your documentation, since the version doesn't jump out of every example request the way /v2/ does. And caching gets more complicated — proxies and CDNs need to respect Vary: Accept or Vary: API-Version correctly, which not all of them do out of the box. Custom headers are simpler to implement than full media-type negotiation but are non-standard — there's no HTTP spec defining what API-Version means, so its behavior is whatever you document it to be.

Content negotiation in depth

The Accept-header approach isn't just "header versioning with extra steps" — it's the formal mechanism HTTP already defines for this exact problem. Content negotiation lets a client and server agree on which representation of a resource to exchange, using headers like Accept, Accept-Language, and Accept-Encoding. Media-type versioning extends that idea: instead of negotiating between application/json and application/xml, you negotiate between application/vnd.company.v1+json and application/vnd.company.v2+json, both of which happen to be JSON but represent different schemas.

This is arguably the most "correct" approach per the HTTP specification. A single, stable URI identifies the resource — exactly one /users/42 — and the version becomes a property of the requested representation, not the resource itself. That single endpoint can, in principle, serve multiple simultaneous versions of the same underlying data without any URL duplication, and the server can even negotiate a default (usually the latest stable version) for clients that don't specify one.

The friction is real, though, and it's why most teams don't reach for this by default. Custom media types are unfamiliar to a lot of developers, meaning higher support overhead and more confused first API calls. They're awkward to test from a browser or a quick curl command without remembering the exact vendor MIME type string. Framework and gateway tooling — routing, API documentation generators, mocking tools — often assumes URI- or query-based versioning and needs extra configuration to branch on media type instead. And because the version is buried in a header rather than the URL, it's easy for a new integration to omit it entirely and get a "surprise" default version.

Semantic versioning vs simple incrementing, and deprecation policy

A separate decision, orthogonal to URI vs. header vs. content negotiation, is how granular your version numbers should be. Most public APIs use simple whole-number increments at the API level — v1, v2, v3 — rather than full semantic versioning (major.minor.patch). Semver is designed for software packages where clients pin exact dependency versions; for HTTP APIs, where every request is independent and clients can't "pin" a running server, that granularity is rarely useful. What matters to an API consumer isn't whether a change is a minor or patch bump — it's whether their existing request/response handling still works. That's a binary: breaking or not breaking.

A related question is whether to version the whole API as a unit or version individual resources independently. Whole-API versioning (a single v1/v2 covering every endpoint) is simpler to reason about and document, but it forces a full major bump even when only one resource changed, which can feel heavy-handed. Per-resource versioning is more surgical — you might have /v2/orders while /v1/users is untouched — but it multiplies the number of version combinations a client has to track and test against, and it complicates your changelog. Most teams start with whole-API versioning for simplicity and only split resources out if a single subsystem is churning much faster than the rest.

None of this matters much, though, if you don't pair it with a real deprecation policy. The versioning scheme is just the mechanism; the deprecation lifecycle is what actually protects your consumers. A workable policy includes: a Deprecation response header (or documented equivalent) as soon as a version enters end-of-life status, a Sunset header carrying the actual removal date once one is set, advance notice in release notes and, ideally, direct email or dashboard alerts to registered API consumers, and a minimum notice window — six to twelve months is common for public APIs — between announcing deprecation and actually turning a version off.

A real-world example

Picture a company running v1 and v2 of its API simultaneously behind a single API gateway, using URI-prefix routing: requests to /v1/* are routed to the legacy service, requests to /v2/* go to the current one. When v2 ships with a redesigned pagination model and a breaking change to how order totals are represented, the team doesn't shut off v1 immediately. Instead, they publish a deprecation notice in the docs and changelog, set a concrete removal date six months out, and start returning Sunset: Sat, 31 Jan 2027 00:00:00 GMT plus Deprecation: true on every v1 response.

Over those six months, they track which API keys are still hitting v1 endpoints and reach out to the highest-traffic consumers directly rather than waiting for them to notice a header. A week before the sunset date, v1 responses start including a warning banner in the response body's metadata as a last-resort nudge. On the sunset date itself, v1 routes return 410 Gone with a body pointing to the v2 migration guide, rather than simply disappearing or silently changing behavior. The gateway-level routing means none of this required touching application code in the v2 service — it was purely a matter of keeping the old service alive, instrumented, and clearly labeled until the deadline passed.

Common mistakes to avoid

The first and most damaging mistake is shipping a breaking change without bumping the version at all — silently altering a field type, removing a field, or changing error codes on an existing version. This is worse than a badly chosen versioning scheme, because it violates the one promise versioning exists to make: that a given version's contract is stable. If it happens even once, consumers stop trusting your version numbers and start defensively coding against every possible response shape.

The second is versioning too aggressively for changes that aren't actually breaking. Adding a new optional field to a response, adding a new endpoint, or accepting an additional optional request parameter are all additive changes that well-behaved clients should tolerate without modification. Bumping the major version for these trains consumers to expect version churn constantly, and it multiplies your maintenance burden for no real safety benefit. Reserve version bumps for genuinely breaking changes: removed or renamed fields, changed types, altered semantics, or removed endpoints.

The third is removing an old version abruptly instead of running a real deprecation window. Even a technically well-designed versioning scheme fails its purpose if "sunset" means "we turned it off with two weeks' notice buried in a changelog nobody reads." The deprecation communication — headers, docs, direct outreach, a genuinely usable lead time — is what consumers actually experience; the URI-vs-header decision is comparatively invisible to them.

Frequently asked questions

Do I need to version my API from day one, even before I have external consumers?
It's cheap insurance to add a version indicator (even just /v1/) before your first public release, because retrofitting versioning onto live URLs that clients already depend on is far more disruptive than starting with it. You don't need a second version yet — you just need the seam to exist.

Can I mix strategies, like URI versioning for major breaking changes and headers for smaller variations?
Yes, and it's fairly common. A typical pattern is URI versioning for the small number of major, breaking contract changes (v1, v2), combined with a custom header or query parameter for opt-in features or beta behavior within a version. Just document the interaction clearly, since layering two mechanisms without explanation confuses consumers fast.

How many versions should I support at once?
Most teams cap it at two: the current version and the immediately prior one during its deprecation window. Supporting three or more simultaneously usually means your deprecation timelines are too loose or aren't being enforced, and it multiplies testing and operational surface area for every change you ship going forward.

There's no universally "correct" versioning strategy — URI versioning wins on simplicity and visibility, header versioning keeps URIs clean at the cost of discoverability, and content negotiation is the most spec-correct but the least ergonomic for most teams. What separates APIs that age well from ones that accumulate consumer resentment isn't which mechanism they picked; it's whether they paired it with a disciplined deprecation policy, restrained their version bumps to genuinely breaking changes, and gave consumers enough notice and enough signal to migrate on their own schedule.