API Versioning Without Breaking Client Apps: A Guide
Learn how to evolve an API without breaking client apps, from URL and header versioning strategies to deprecation windows, sunset notices, and a safe v2 rollout.
The Short Answer
API versioning is how a team changes an application programming interface without breaking the apps that already depend on it. Every field, endpoint, and validation rule in an API is a promise to someone else's code, and when that promise changes without warning, mobile apps crash, integrations stop syncing, and support tickets pile up. A…
API versioning is how a team changes an application programming interface without breaking the apps that already depend on it. Every field, endpoint, and validation rule in an API is a promise to someone else's code, and when that promise changes without warning, mobile apps crash, integrations stop syncing, and support tickets pile up. A practical versioning plan treats stability as a feature: it lets an API evolve while giving every client a clear, predictable path from an old contract to a new one.
This guide serves both sides of that promise. Builders will learn how to choose a strategy, plan deprecation windows, and ship a new major version without forcing a same day migration. Buyers will learn the questions to ask before approving a vendor roadmap.
Why API versioning matters for every client app
An API rarely serves one client. The same endpoints may feed a website, an iOS app, an Android app, and a partner dashboard, each updating on a different schedule. A mobile app already installed on a user's phone cannot be updated by the server team, and a partner integration may only be touched once a quarter. Without a version boundary, a breaking change forces every client to change at the same moment, whether it is ready or not.
Good API versioning lets old and new contracts run side by side. Version 1 keeps working while version 2 is tested and adopted in stages, so clients migrate when their own release cycle allows it. That is why mature platforms such as Stripe, GitHub, and Twilio publish explicit versioning and deprecation policies.
API versioning strategies: URL, header, and date based approaches
There are three widely used ways to tell the server which version a client wants. The choice matters less than consistency, because switching strategies midstream confuses every consumer, but each approach has trade offs worth understanding before committing.
URL versioning
URL versioning puts the major version in the path, for example /api/v1/orders and /api/v2/orders. It is easy to read, test, route, and cache, because each version has its own distinct address, and documentation and logs show the version at a glance. For public and partner APIs, this clarity usually outweighs the slightly longer URLs.
Header versioning
Header versioning keeps the URL stable and sends the version in a header, such as Accept: application/vnd.example.v2+json or X-API-Version: 2. URLs stay clean, but a developer cannot see the version from the URL, browser testing is harder, and caching must vary correctly on the header. It suits internal APIs with controlled clients.
Date based versioning
Date based versioning, popularised by Stripe, pins each client to the behaviour that existed on a chosen date, for example Stripe-Version: 2024-12-18. Changes roll out as dated snapshots, and each client upgrades by moving its pinned date forward when ready. This suits frequently evolving platforms, but tracking which behaviours belong to which date adds complexity. For most small and mid sized APIs, URL versioning with a clear deprecation policy is simpler.
| Strategy | Best for | Watch out for |
| URL path | Public and partner APIs | Longer URLs, duplicated routes |
| Header | Internal APIs, controlled clients | Harder to test, cache, and debug |
| Query parameter | Quick prototypes only | Easy to forget, weak caching |
| Date based | Frequently evolving platforms | Complex behaviour tracking |
Apply one strategy consistently from the first release. Add the version on day one, even when only v1 exists, because adding versioning after clients have integrated without it is itself a breaking change. Current 2025 and 2026 guidance follows a simple rule: minor additions and bug fixes stay inside the same version, and only a change that would break a valid existing client earns a new major version. Teams that need help applying this can work with specialists in API development and integration.
API versioning rules: what breaks a client and what does not
Backward compatible, or additive, changes do not break clients that parse normally. Adding a new optional response field, a new endpoint, or a new optional request parameter is safe inside the same version, because a well written client ignores fields it does not recognise.
Breaking changes are anything that can invalidate a request or response a client already makes correctly: removing a field, renaming a field, changing a field type, removing an endpoint, adding a required request field, tightening a validation rule so previously accepted input is rejected, or changing error codes that clients branch on. Any one of these inside an existing version breaks the promise. Never change the meaning of an existing field while keeping its name, because clients cannot detect that change.
- Safe in the same version: new optional fields, new endpoints, and new optional parameters.
- Breaking, needs a new major version or a shim: field removal, field rename, type change, required field addition, stricter validation, and error shape change.
A useful test before shipping is to ask: would a client that passed all tests yesterday still pass all tests tomorrow, with no code change? If not, the change is breaking, and it belongs behind a version boundary or a compatibility layer.
Deprecation windows and sunset notices that clients can actually act on
Deprecation is not deletion. It is a published promise that an old version will keep working until a stated date. Current 2025 and 2026 guidance points to a deprecation window of 6 to 12 months for public APIs, with longer windows when mobile apps or slow moving partners are involved.
A strong plan uses four signals together. Mark the operation deprecated in the documentation and OpenAPI specification, with the sunset date and a migration guide link. Send the Deprecation and Sunset response headers defined in RFC 8594 on every response from the deprecated version, so client middleware can log the warning automatically. Include a Link header pointing to the successor version. Notify account owners directly at 90, 30, and 7 days before sunset.
After the window ends, return a clear 410 Gone response with a machine readable error code and a migration guide link, rather than a generic 404. Monitor deprecated version usage, contact remaining users personally, and switch off the old version only once real traffic has fallen to zero. For running versions in parallel, see this guide to zero downtime deployment.
A real breaking change, walked through: renaming a customer field
Consider an ordering API. Version 1 returns a customer object with one field called name, holding the full name as one string, for example "Ayesha Khan". The product team now wants separate firstName and lastName fields, because search, personalisation, and shipping labels need the parts separately. Renaming name to firstName and lastName looks tidy, but it is a textbook breaking change: every client reading customer.name will suddenly get nothing, and order screens, invoices, and CRM syncs will show blank names.
The rollout that keeps existing clients working has five steps, and none requires a same day migration.
- Add without removing: add firstName and lastName alongside name, populated from the same data. Old clients ignore the new fields; new clients use them immediately.
- Accept both on input: accept name, firstName, and lastName during the transition, with a documented precedence rule when both forms arrive. Never reject a request that was valid yesterday.
- Announce v2 and deprecate the old field: publish v2 with firstName and lastName as canonical, mark name as deprecated, and set a sunset date with a full migration window.
- Migrate in waves: move internal clients first, then high traffic partners, then the long tail, watching name usage in logs at each stage, with a short migration guide showing before and after examples.
- Remove last: once logs show no live use of name and the sunset date has passed, remove it in v2 only, leaving v1 untouched until its own sunset date.
The same pattern handles tightening a validation rule. Suppose v1 accepts any positive order quantity, and the business now wants a maximum of 999 per order. Rejecting 1000 on day one breaks bulk buyers who relied on the old limit. Instead, add the limit to v2, warn in v1 when a quantity exceeds the future limit, publish the new rule with a migration window, and enforce it only in v2. The principle is identical: warn first, support both forms, remove last.
Error responses that tell the client what to do next
When a client calls a deprecated or removed version, the error response is part of the versioning contract. A vague message wastes hours of debugging; a structured error lets client code handle the problem automatically. Every error should share the same JSON shape, with a stable machine readable code, a human readable message, and a request ID for support.
For versioning, three patterns matter most. A request to an unknown version should name the supported versions. A request to a deprecated version should still succeed during the window, but carry Deprecation and Sunset headers so automation can flag it. A request after sunset should return 410 Gone with the successor link, not a generic not found error. Clients can then branch on the code, rather than guessing from free text.
How to ship a v2 without forcing every client to migrate on day one
Shipping v2 is a launch, not a switch off. Run both versions in production in parallel, with the same business logic underneath and a thin transformation layer shaping each response to its version contract. Duplicating the whole service per version doubles bugs and drift.
Deploy v2 alongside v1 with no traffic, test both versions with the same automated suite, including contract tests that fail if a v1 response shape changes accidentally, then invite one or two friendly clients to adopt v2. Publish the migration guide, the changelog, and the v1 sunset date, then let v1 enter its deprecation window, with usage monitoring driving the timeline. If a major client cannot migrate by the original date, negotiate an extension rather than breaking them.
For buyers, ask the vendor: which versioning strategy do you use, how long is your deprecation window, do you send Sunset headers, and can you show a past migration guide? Vague answers are a warning sign. For a wider view, read this complete business guide to API integration, and this comparison of custom versus off the shelf software.
API versioning checklist for builders and buyers
- Version from day one, using one consistent strategy across all endpoints.
- Never ship a breaking change inside an existing major version.
- Prefer additive changes, and use dual fields during any rename.
- Publish a 6 to 12 month deprecation window for public APIs, with Sunset headers and direct notices.
- Run v1 and v2 in parallel, sharing business logic behind version specific transformers.
- Test every supported version in automation, and monitor deprecated usage until it reaches zero.
- Return structured errors with stable codes, request IDs, and successor links after sunset.
- Write a migration guide with before and after examples for every major version.
Frequently asked questions about API versioning
What is API versioning?
API versioning labels each major contract of an API, usually as v1, v2, and so on, so breaking changes can ship in a new version while existing clients keep using the version they tested against until they are ready to migrate.
Is URL versioning or header versioning better?
URL versioning is usually better for public and partner APIs because the version is visible, easy to test, and easy to cache. Header versioning suits internal APIs with controlled clients where clean URLs matter more than discoverability.
How long should a deprecated API version stay live?
For public APIs, current guidance points to 6 to 12 months from announcement to sunset, with direct notices at 90, 30, and 7 days before removal. Internal APIs can use shorter windows, but the window should still be written down and honoured.
Does adding a new field require a new API version?
No, adding an optional field is backward compatible and needs no new major version, provided clients ignore unknown fields. Removing or renaming a field, changing a type, or adding a required field is breaking and needs a new version or a compatibility shim.
What should happen when a client calls a removed version?
The API should return 410 Gone with a stable error code, a clear message, and a link to the successor version or migration guide, rather than a generic not found error.
Can I avoid versioning by never breaking anything?
Additive evolution can delay a new major version for a long time, but most successful APIs eventually need a genuine breaking change, such as a field rename or a stricter rule. Versioning is the safety net that makes that day survivable, so set it up before you need it.
API versioning is ultimately a statement about how you treat the people who build on your work. A version boundary, a fair deprecation window, and an error message that points forward all say the same thing: your app matters, and we will not break it without warning.
If you are planning a new API, or you need to untangle a versioning problem in an existing one, Contact Skills Technology Solutions to discuss your API roadmap and migration plan.
Related Articles
Keep reading — more guides you may find useful.
Related Services
Services connected to this guide.
