API Versioning Without Breaking Existing Clients
You renamed one field in a JSON response, deployed on a Tuesday afternoon, and by Wednesday morning a partner's mobile app was crashing for 30,000 users who had not updated in months.

You renamed one field in a JSON response, deployed on a Tuesday afternoon, and by Wednesday morning a partner's mobile app was crashing for 30,000 users who had not updated in months. That is the problem API versioning exists to solve: your API has to keep changing, but clients you do not control keep running old code for a very long time. A good versioning strategy lets you ship changes without forcing everyone to upgrade on your schedule.
This guide covers what actually counts as a breaking change, the three common ways to version an API, how to run a deprecation, and why I think most teams version far more often than they need to.
What counts as a breaking change
Versioning only matters for breaking changes, so the first job is knowing which changes break clients. A useful rule: a change is breaking if any reasonably written client could stop working without touching its own code.
Usually breaking
- Removing or renaming a field in a response.
- Changing a field's type, such as an integer ID becoming a string.
- Making an optional request parameter required.
- Changing the meaning of a value, such as prices switching from dollars to cents.
- Changing status codes, for example returning 200 with an empty list where you used to return 404.
- Tightening validation, such as rejecting names longer than 50 characters that used to be accepted.
Usually safe
- Adding a new optional field to a response.
- Adding a new endpoint.
- Adding an optional request parameter with a sensible default.
- Adding a new value to an enum, but only if clients were told to handle unknown values.
That last point catches a lot of teams. If your documentation never said "ignore unknown enum values," then adding a new order status like "partially_refunded" can crash a client with a strict switch statement. Write that rule into your docs on day one.
Three ways to handle API versioning
1. Version in the URL path
Requests go to /v1/orders or /v2/orders. This is the most common approach and the easiest to see in logs, test in a browser and route at the load balancer. The downside is that a version bump applies to the whole API, even if only one endpoint changed, and URLs stop being stable identifiers for a resource.
2. Version in a request header
Clients send something like an Api-Version header with a value such as 2026-11-01, or a custom media type in the Accept header. URLs stay clean and you can version per request. The cost is visibility: headers are easy to forget in a quick curl test, harder to see in access logs, and some caching layers ignore them unless you set the Vary header correctly.
3. Date-based versions pinned per client
Each API key is pinned to the version that was current when the client first integrated. The server keeps a chain of small transformations that convert the newest internal response back into each older shape. Clients upgrade by changing their pinned date when they are ready. This scales well for public APIs with thousands of integrators, but it requires real engineering discipline to keep the transformation chain tested.
| Approach | Best for | Main cost |
|---|---|---|
| URL path | Internal APIs, small public APIs | Whole-API bumps, duplicated routes |
| Header | APIs with frequent, small changes | Less visible, caching care needed |
| Date-pinned | Large public APIs with many partners | Transformation layer to maintain |
The counter-take: version less, evolve more
The common advice is to "version everything from the start and bump the version whenever something changes." I think that leads to version sprawl. Teams end up running v1, v2, v3 and v4 side by side, each with its own bugs, tests and on-call pages, and most clients never move past v2 anyway.
A better default is to put /v1 in place from the start, then treat a new major version as a rare, expensive event, maybe once every two or three years. Between those events, evolve the API additively. Need a new shape for addresses? Add a structured_address field next to the old address string, keep both populated, and document the old one as deprecated. You get almost all the benefit of a new version with none of the parallel infrastructure. Additive design is easier when the original API was predictable, which is a theme in our guide on designing a REST API other developers enjoy using.
Running a deprecation that clients actually notice
Most deprecations fail because nobody reads the announcement. A process that works:
- Measure first. Log the version and client ID on every request. You cannot retire v1 if you do not know who still calls it.
- Announce with a date. Give at least six months for public APIs and 60 to 90 days for internal ones. State the exact shutdown date, not "soon."
- Signal in responses. Add a Deprecation header and a Sunset header with the shutdown date to every response from the old version. Many client libraries and API gateways surface these automatically.
- Contact the top callers directly. Usually 10 to 20 clients make up 90 percent of old-version traffic. An email to each beats any blog post.
- Run brownouts. Two to four weeks before shutdown, return errors from the old version for short windows, such as 15 minutes at a scheduled time. Forgotten integrations surface quickly.
- Shut down, then watch. Return a clear 410 Gone with a link to migration docs instead of a generic 404.
Keeping old versions cheap to run
Every live version costs something. A few habits keep that cost low:
- One codebase, thin adapters. Keep a single core implementation and translate requests and responses at the edge. Forking whole controllers per version doubles every future bug fix.
- Contract tests per version. Store example requests and expected responses for each supported version and run them in CI. A refactor that silently changes v1 output gets caught before deploy.
- Shared cross-cutting behavior. Authentication, rate limits and retry semantics should not differ between versions. If v1 and v2 handle duplicate POST requests differently, clients get confused; our article on how idempotency keys stop duplicate API requests covers a pattern that should work identically everywhere.
For more on keeping services stable under change and load, browse the rest of our back-end guides.
Frequently asked questions
Should API versions go in the URL or the header?
For most teams, the URL path is the practical choice because it is visible, easy to route and easy to test. Header versioning suits APIs with frequent small changes and clients that are comfortable setting headers. Either works if you apply it consistently.
How long should you support an old API version?
Public APIs commonly support an old version for 12 to 24 months after a replacement ships, with at least six months' notice before shutdown. Internal APIs can move faster, often within one quarter, because you can contact every client directly.
Is adding a field to a JSON response a breaking change?
Usually not, as long as clients ignore fields they do not recognize, which most JSON parsers do by default. It can break clients that validate responses against a strict schema, so document that unknown fields may appear at any time.
More in Back-End
Back-End
How to Run Database Migrations Without Locking Tables
The migration itself took 41 milliseconds. The outage lasted nine minutes.
Back-End
How Graceful Shutdown Stops Deploys From Dropping Requests
Every deploy at a job I had before this one left a small notch in the error graph.
Back-End
How to Deliver Webhooks Reliably With Retries and Signing
A partner emails to say they never received the order.created event from last Tuesday.