# How to Version a REST API Without Breaking Existing Clients > A practical guide to REST API versioning strategies — URL path, headers, and media types — so you can ship changes without disrupting live consumers. - **Published:** 2025-12-01 - **Author:** Clixo - **Reading time:** 5 min read - **Tags:** api-design, rest, versioning, backend - **Canonical URL:** https://clixo.sh/blog/rest-api-versioning-without-breaking-changes You shipped a REST API. Clients are live. Now you need to change a field name, drop an endpoint, or restructure a response body. Without a versioning strategy in place, every breaking change is a production incident waiting to happen. Most teams reach for versioning only after they have already broken something. That is the wrong order. This guide walks through the main strategies, their trade-offs, and what to actually do in practice. ## REST API Versioning Strategies There are three main places to put a version signal: the URL path, an HTTP header, or the media type. Each has a different operational profile. ### URL Path Versioning The most common approach. You prefix every endpoint with a version segment: ``` GET /v1/users/42 GET /v2/users/42 ``` **Why teams choose it:** it is visible in logs, easy to test in a browser, and works with every HTTP client without configuration. API gateways and load balancers can route by path prefix with zero custom logic. **The downside:** URLs are supposed to identify resources, not API contracts. Technically, `/v1/users/42` and `/v2/users/42` refer to the same user — the version is a contract detail, not a resource detail. For many teams, this is an acceptable pragmatic trade-off. ### Header-Based Versioning The client sends a version token in a custom request header: ``` GET /users/42 API-Version: 2 ``` **Why teams choose it:** keeps URLs clean, separates transport from contract. Works well when you control both the client and the server and can enforce header presence at the gateway layer. **The downside:** less visible, harder to test directly in a browser or curl. Caching behavior at CDN and proxy layers can be unpredictable unless you set `Vary: API-Version` correctly. ### Media Type (Content Negotiation) Versioning The client declares the version in the `Accept` header: ``` Accept: application/vnd.myapi.v2+json ``` This is the most REST-principled approach — it maps cleanly to HTTP semantics. In practice, it is also the most complex to implement and the rarest in the wild. Reserve it for public APIs where precise HTTP semantics matter more than developer ergonomics. ```mermaid flowchart LR A["v1 released"] --> B["v1 active and supported"] B --> C["Breaking change needed"] C --> D["v2 released"] D --> E["Sunset header added to v1"] E --> F["6-month deprecation window"] F --> G["v1 retired"] D --> H["v2 active and supported"] ``` ## What Actually Works in Production Pick one strategy and apply it consistently. Mixing URL versioning for some endpoints and header versioning for others produces a support nightmare. **For most product teams:** URL path versioning wins on developer experience and operational simplicity. The philosophical purity argument is real, but it costs you every time a developer has to remember to set a header. **For internal service-to-service APIs:** header versioning is reasonable when clients are controlled services that you own, and when you have an API gateway enforcing the header contract. ## Backward Compatibility Before Versioning The best version is the one you do not need to cut. Before bumping a version, ask whether the change is actually breaking: - **Additive changes are safe.** New optional fields in responses, new optional query parameters, new endpoints — none of these break existing clients. - **Removals and renames are breaking.** Removing a field, changing a field's type, or renaming a parameter forces clients to update. Design your response bodies with extensibility in mind from day one. Clients should ignore unknown fields. If your client SDKs strip unknown fields during deserialization, fix that first. ## Managing Multiple Versions Once you cut a new version, you owe existing clients a sunset plan. **Give at least six months notice.** Put a `Sunset` header on deprecated endpoints: ``` Sunset: Sat, 01 Jun 2026 00:00:00 GMT Deprecation: true ``` **Run both versions in CI.** Every deployment should run contract tests against all supported versions. If v1 tests fail, do not ship — even if you only changed v2 code. Shared middleware, database schema changes, and library upgrades can break old versions unexpectedly. **Keep version logic thin.** The goal is to run one codebase that serves multiple versions, not a separate codebase per version. Transformation layers at the edge (request/response adapters) are cleaner than branching deep inside business logic. ## Version Zero Is Still a Version If you are building an API that is not yet public, resist the temptation to skip versioning. Starting at `/v1/` costs nothing. Starting at `/api/` and then trying to introduce `/v1/` after clients are live costs a migration. ## Common Mistakes to Avoid - **No deprecation notices.** Clients find out their integration is broken when it stops working, not before. - **Breaking changes inside a version.** Once a version is live, it is frozen. New behavior goes in a new version. - **Too many versions in flight.** Supporting more than two active versions (current and previous) adds significant operational overhead. Set a policy and enforce it. - **Omitting `Vary` headers.** If you use header-based versioning behind a CDN, cached responses may serve the wrong version silently. ## The Operational Reality Versioning is not a one-time design decision — it is an ongoing operational commitment. Cutting a version is easy. Maintaining it, communicating deprecation timelines, and running regression suites across versions is where most teams underinvest. The teams that get this right treat each version like a supported release branch: it gets security patches, it has known end-of-life dates, and clients are actively migrated off it before the sunset date arrives. If you are building a new API or rearchitecting an existing one and want versioning baked in from the start, [talk to the Clixo team](https://clixo.sh/#contact). We design and build backend systems where this kind of operational discipline is built into the contract from day one. --- Clixo · 1141 W Bryn Mawr Ave, Itasca, IL 60143, US · [hello@clixo.sh](mailto:hello@clixo.sh) [Start a build](https://clixo.sh/#contact) · [All services](https://clixo.sh/services) · [Agent guide (llms.txt)](https://clixo.sh/llms.txt)