Every API starts as a promise. Once a mobile app, a partner integration or a customer script depends on your response shape, that shape belongs to them as much as to you. Rename one field and an app that shipped six months ago starts crashing on phones you cannot update.
Yet APIs have to change. Products evolve, data models get cleaned up, and security requirements tighten. The teams that handle this well do not avoid change. They treat versioning as a product decision with a policy, a process and an owner, not as a URL prefix added at the last minute.
In this guide, you'll learn:
- How URL, header and date-based versioning compare in practice
- Which changes are safe to ship without a new version
- How to run, deprecate and retire versions without surprising anyone
We build APIs for web, mobile and partner clients every week, and the same lessons keep repeating.
Table Of Contents
1. Why API Versioning Matters
A web client can be redeployed in minutes. A mobile app cannot. Users stay on old builds for months, and some never update. Every public API therefore serves a long tail of client versions at once, and the oldest of them sets your real compatibility floor.
Partner integrations raise the stakes further. Their release cycle is not yours, and a breaking change on your side becomes an outage on theirs, followed by a support escalation to you.
Versioning gives you a contract boundary. It lets you say: this behavior is frozen, and new behavior lives over there. Without it, every change is a gamble, and teams respond by freezing the API entirely, which slows the product down in a different way.
Illustrative example
2. Choosing a Versioning Scheme
There is no universally correct scheme. There is the one that fits your clients and your team. These are the three we see most often.
| Scheme | Example | Strength | Weakness |
|---|---|---|---|
| URL path | /v2/orders |
Obvious, easy to route and cache | Version applies to the whole API |
| Header or media type | Accept: application/vnd.app.v2+json |
Clean URLs, per-resource control | Harder to test by hand and to debug |
| Date-based | API-Version: 2026-03-01 |
Fine-grained, no big-bang releases | Needs tooling to manage transforms |
2.1 URL path versioning
This is the default for most teams, and for good reason. It is visible in logs, easy to document and trivial for gateways and CDNs to route. The cost is granularity: bumping to v2 for one changed endpoint tempts you to copy everything else.
2.2 Header and date-based versioning
Header schemes keep URLs stable and let each resource evolve on its own. Date-based versions go further: each client is pinned to the date it integrated, and changes are applied as small transforms on top. It is powerful, but it demands investment in internal tooling.
Pro Tip: If your clients are mostly mobile apps or third parties you cannot coordinate with, choose the simplest scheme your team can run consistently. A boring URL version that is enforced beats a clever scheme that is half implemented.
3. Designing Changes That Do Not Break Clients
The best version is the one you never need to cut. Most changes can be shipped additively if you design for it.
3.1 Safe changes
- Adding a new optional field to a response
- Adding a new endpoint
- Adding an optional request parameter with a sensible default
- Adding a new enum value, if clients were told to tolerate unknown values
3.2 Breaking changes
- Removing or renaming a field
- Changing a field's type or meaning, even subtly
- Making an optional parameter required
- Changing error codes or the shape of error bodies
- Tightening validation that used to accept input
The quiet ones are the dangerous ones. Changing a price from an integer to a string, or a timestamp from local time to UTC, passes every compile check and still breaks clients. Document your tolerance rules (ignore unknown fields, handle unknown enum values) in your public API guidelines so clients can build for them.
4. Running Multiple Versions in Code
Supporting two versions must not mean maintaining two codebases. The pattern that works is a single internal domain model with a thin translation layer per version.
- 1Requestv1, v2 or v3 route
- 2Version adaptermaps to internal input
- 3Core serviceone implementation
- 4Response transformershapes the old or new output
Illustrative example
Keep business rules in the core service and keep each version's request and response mapping in small, isolated classes or resources. When v1 is retired, you delete its adapters and nothing else changes.
Avoid branching on the version inside business logic. The moment an if ($version === 1) appears in a service, you have created permanent debt that no one will dare to remove.
Pro Tip: Give every version adapter its own contract tests. When a core change accidentally alters an old response, those tests catch it before a client does.
5. Deprecation and Sunset Policy
Retiring a version is a communication problem more than a technical one. Publish the policy before you need it, so no one is surprised.
A workable policy states the minimum support window (for example, twelve months after a successor is released for mobile-facing APIs), how you announce deprecations, and what happens on the sunset date.
Use the machine-readable signals too. The Deprecation and Sunset HTTP response headers tell client developers, and their monitoring tools, that a date is coming. Pair them with emails to the account owners you can identify from your API keys.
Then watch the traffic. Dates in a changelog do not retire versions. Usage dropping to zero does. If a large client is still on the old version at sunset, reach out personally rather than switching it off on schedule.
6. Testing and Monitoring Compatibility
Compatibility is easy to break and hard to notice. Automate the checks.
- Schema diffing in CI. Compare your OpenAPI spec against the last released one and fail the build on any breaking diff.
- Contract tests. Record real request and response pairs from each supported version and replay them against every build.
- Per-version metrics. Track request volume, error rate and latency by version, and by client where you can. A rising error rate on one old version often means a regression only that version exposes.
- Client identification. Require an app or SDK version header so you know who is actually calling.
These habits turn versioning from a hope into a measurable guarantee.
7. Frequently Asked Questions
Should I version my API from day one?
Yes, if it will have external or mobile clients. Starting with /v1 costs almost nothing, while retrofitting a version later forces every existing client to change.
When do I actually need a new major version?
Only when a change cannot be made additively: removing or renaming fields, changing types or semantics, or altering error contracts. Try to batch breaking changes into one planned release.
How long should I support an old version?
It depends on who your clients are. For mobile-facing APIs, twelve months or more after a successor ships is common. Use per-version traffic data to confirm usage has dropped before sunsetting.
Does GraphQL remove the need for versioning?
It reduces it, because clients request only the fields they need and you can deprecate fields individually. You still need a policy for removing fields and for changing their meaning.
Conclusion
Good API versioning is mostly discipline. Prefer additive changes, choose one scheme and enforce it, isolate version differences in thin adapters, publish a deprecation policy, and let real traffic tell you when it is safe to retire something. Do that and your API can keep evolving while the clients you already shipped keep working.
Next time you plan a change, ask first whether it can be additive. Often it can.
💬 What is the oldest API version your team still supports, and what keeps it alive?
Comments