API Versioning & Deprecation: Getting Users Off v1

Q: What actually counts as a breaking API change?

Anything that causes a previously-working consumer integration to stop working — which is a broader set than schema changes and is the distinction most teams get wrong in both directions. Clearly breaking: removing or renaming a response field, making an optional request field required, narrowing an accepted value range or enum, changing an error code or HTTP status, and changing authentication requirements. Clearly safe: adding an optional request field, and adding a new endpoint. The contested middle is where incidents live. Adding a response field is usually safe but breaks consumers using strict schema validation, and more of them do than you expect. Adding an enum value looks purely additive and is not: a consumer with an exhaustive switch statement hits an unhandled case in production, which is why mature APIs document enums as open-ended from the first release and why some consumers break anyway. And the category teams most often miss entirely: behavioural changes with an untouched schema. If your endpoint has always returned results newest-first, changing the default order breaks consumers who relied on it. Changing default pagination size, numeric precision, or timing characteristics does the same. Tightening a rate limit breaks working integrations without altering a single field. The governing principle is Hyrum's law — with enough consumers, every observable behaviour of your system becomes something someone depends on, regardless of what you documented. The practical implication is that you cannot determine what is breaking from the specification alone; you need to know what consumers actually do, which is why per-consumer usage instrumentation and consumer-driven contract tests matter more than a careful reading of your own schema.

Q: Should I use URL path versioning or header versioning?

URL path versioning is the pragmatic default for most public APIs, and the choice matters far less than the deprecation policy behind it. URL path versioning (`/v1/orders`) wins on operational clarity: the version is visible in logs, trivially routable at the gateway, unambiguous in caching layers, testable in a browser, and immediately obvious to anyone reading integration code. Its genuine cost is granularity — the version applies to the whole surface, so a breaking change in one endpoint drags every other endpoint to `/v2`, which pushes teams toward large, infrequent, painful migrations rather than small continuous ones. Header or media-type versioning keeps URLs stable and versions the representation, which is more correct in REST terms and genuinely useful when you want content negotiation. Its costs are operational rather than theoretical: it is harder to exercise in a browser or curl one-liner, easier to get wrong in caches and CDNs (you must vary on the header, and forgetting is a subtle production bug), and invisible in logs and analytics unless you deliberately capture it. Date-based or account-pinned versioning, as Stripe does, pins each consumer to the version current at integration and applies server-side compatibility transformations so old integrations keep seeing old behaviour. It is the best consumer experience available and the highest ongoing engineering cost, because you maintain a growing chain of transformations indefinitely — a commitment most teams should decline. My practical recommendation: use URL path versioning, keep versions rare by preferring additive change, and spend the effort you saved on the things that actually determine outcomes — knowing who calls what, publishing a deprecation policy before you need it, and signalling sunset in-protocol.

Q: How do I get consumers to migrate off an old API version?

By making migration cheap, giving a real deadline that was published before they integrated, and knowing exactly who is left — in that order, because the common failure is announcing a deadline to an anonymous audience and discovering you cannot enforce it. Start with knowing: instrument usage per consumer, per endpoint, per version. Without this, "can we remove v1?" is unanswerable, so the answer defaults to no permanently. With it, you typically discover that most traffic moved long ago and a handful of specific consumers remain — which converts a broadcast problem into eleven direct conversations, an entirely different and far more tractable task. Then make it cheap: a migration guide showing concrete before-and-after for the actual changes, a compatibility shim where feasible, and where possible a migration you perform on their behalf rather than requiring their engineering time. Every hour of consumer effort you remove raises your migration rate more than any amount of urgency in the announcement. Then the deadline, which only works if the policy predates the integration — a support window published upfront is the deal they accepted, while one introduced afterwards reads as a change of terms and invites escalation. Signal it through every channel: `Sunset` and `Deprecation` headers so the calling system notices even though the developer who integrated has left, plus email to registered developers, changelog entries, and in-console warnings. Finally, escalate deliberately rather than abruptly: warnings, then direct outreach to the named remaining consumers, then optionally brownouts (short deliberate outages of the old version at announced times, which reliably surface integrations nobody was monitoring), then removal. The pattern that fails is a single announcement followed by an indefinite extension, because that teaches every consumer that your deadlines are advisory.

Q: What is expand-and-contract and why is it better than versioning?

Expand-and-contract evolves an API without a new version by adding the new shape alongside the old, running both while consumers migrate, and removing the old only once usage reaches zero. It is better than versioning where it applies because it avoids the version explosion entirely — you never accumulate parallel surfaces with divergent behaviour and separate bug fixes. Concretely: to rename a field, add the new field while continuing to populate the old; to change a response structure, add a new endpoint or an opt-in parameter; to change a default, make the new behaviour available explicitly first and flip the default only after adoption. At each point both old and new consumers work, which means no coordinated migration, no flag day, and no version number. The contract phase — removing the old field or endpoint — happens on your schedule once instrumentation shows nobody uses it. The reason this matters more than it sounds: most changes teams create a version for could have been additive with modestly more design effort, and that extra design is far cheaper than supporting a parallel version for three years. The same discipline underlies zero-downtime database migrations, where expand-contract-backfill exists precisely because you can never have a moment where old and new code cannot both run. There are genuine limits. Some changes are irreducibly incompatible — removing a capability entirely, or a semantic change where old and new cannot coexist coherently — and those warrant a version. The expand phase also carries interim cost: you maintain both shapes and populate both, which is untidy while it lasts. And contract only completes if you actually instrument usage and follow through, otherwise you have added a field and kept the old one forever, which is the version problem in a different costume.

Q: How long should I support an old API version?

Long enough that a reasonable consumer can migrate within their normal planning cycle, published before they integrate, and short enough that you can actually end it — with the exact number mattering far less than the fact that it was committed to in advance. Practical ranges by context: public APIs with many external consumers commonly commit to 12 months or more from the successor's general availability, because enterprise consumers plan quarterly and some cannot deploy on demand. Partner and B2B APIs with a known consumer list can often work with 6 months, since you can negotiate directly with a finite set. Internal APIs where you control deployment can be far shorter — weeks — because coordination is possible and the "consumers" are colleagues. Security-driven removals are the deliberate exception and your policy should say so explicitly: if a version is dangerous, the timeline is dictated by risk rather than convenience, and reserving that right upfront avoids arguing about it under pressure. Three things matter more than the number. Publish it at integration time so it is the deal rather than a later imposition. Define when the clock starts — usually general availability of the replacement, not its beta — because ambiguity here is where extension requests originate. And commit to actually enforcing it, because the first extension you grant teaches every consumer that your dates are advisory, and after that no deadline works. Two mechanics make enforcement realistic: per-consumer usage data so the endgame is a small number of direct conversations rather than a standoff with an anonymous population, and brownouts — brief announced outages of the deprecated version in the final weeks — which reliably surface integrations that nobody was monitoring and that would otherwise page you the day you actually remove it.

Q: How do consumer-driven contract tests help with API versioning?

They convert "is this change breaking?" from a judgment call made by the producer into a test result produced by the consumers, and they do it before the change ships rather than after it causes an incident. The mechanism: each consumer publishes a contract describing what it actually depends on — the endpoints it calls, the fields it reads, the values it expects — usually generated from its own test suite so the contract reflects real usage rather than aspiration. Your CI runs those contracts against your implementation, and the build fails when a change violates any of them. Tooling such as Pact provides the broker and verification workflow. Why this matters specifically for versioning: the central difficulty is that producers cannot know what consumers depend on, because dependence includes undocumented behaviour that nobody thought to write down. A producer reading their own OpenAPI spec sees the fields they intended to promise; a consumer contract shows the fields actually parsed, the enum values actually handled, and the ordering actually assumed. That difference is exactly where breaking changes hide. Two direct consequences. You can make additive changes confidently, because you know nothing depends on the shape you are extending — which lowers the cost of expand-and-contract and reduces how often you need a version at all. And you can retire fields safely, because the contracts tell you whether anyone still reads them, complementing runtime usage data with design-time knowledge. The main limitation is coverage: contract testing works well for known internal or partner consumers who participate, and does not extend to anonymous public API users who will never publish a contract. For those, runtime per-consumer usage instrumentation is the substitute, and most mature API programmes run both — contracts for the consumers they can enlist, telemetry for the ones they cannot.

Q: What changes when AI agents are the ones calling my API?

The human channel for deprecation stops working, and the consumer's capacity to adapt to your changes drops — both of which push toward more machine-readable signalling and fewer required migrations. Take the deprecation channel first. Traditional practice assumes a developer integrated your API, subscribed to your changelog, and reads your emails. When an agentic client discovers your API from a specification and calls it autonomously, there may be no human monitoring anything — and increasingly the original integrating developer has moved on while the code keeps calling. That makes in-protocol signalling the only reliable channel: `Sunset` and `Deprecation` headers reach the calling system, machine-readable specifications with deprecation annotations reach the tooling, and structured error responses on removal are what an automated client can actually act on. Human channels remain necessary but are no longer sufficient. Second, adaptation capacity. AI-assisted integration means consumers integrate faster and understand less — code generated from your spec works without anyone forming a mental model of your API — so when you change something, there is less contextual understanding available to adapt, and more surprise when things break. That argues for a lower rate of required migration rather than merely better communication about migrations. Practical implications: keep your machine-readable specification accurate and current, since it is now the primary interface documentation for a growing share of consumers; annotate deprecation in the spec itself, not only in prose; return structured, actionable errors that identify the deprecation explicitly rather than a generic 410; and weight expand-and-contract even more heavily, because an additive change requires no adaptation from a consumer who cannot adapt. The general direction is the same one good API design always pointed toward — it has simply stopped being optional.

Q: How do I know if my API versioning is in trouble?

Five questions, and any "no" identifies the specific gap to close. First: can you name, right now, which consumers are calling your oldest live version? If not, you have no path to removal and the answer to "can we deprecate this?" will default to no indefinitely — this is the most common and most consequential gap. Second: is there a published deprecation policy that existed before your current consumers integrated? A policy written after the fact is a negotiation; one published upfront is the terms of the deal, and the difference determines whether your deadlines hold. Third: has any version actually been removed? Organisations that have never completed a removal usually cannot, and the reason is normally the missing instrumentation from the first question rather than consumer intransigence. Fourth: does "breaking" have a written definition that includes behavioural changes — default ordering, pagination, precision, error codes, rate limits — or is it re-litigated per change? Ambiguity here is why some teams version unnecessarily and others ship outages, sometimes both. Fifth: what proportion of your changes are additive? If most changes require a version, you likely have a design habit rather than a genuine compatibility constraint, and expand-and-contract would eliminate most of them. Three warning signs that the situation is already advanced: more than two live versions with no removal date attached to any of them; a roadmap where improvements stall on "we can't break v1"; and different versions having diverged in behaviour beyond the original change, which means you are now maintaining separate products. The remediation order is fixed by dependency: instrument usage first, because every other fix depends on knowing who is actually there.

Satyam Kumar

Volver al Blog

ai-architecture

You Can't Un-Ship an API: Versioning, Deprecation, and Getting Consumers Off v1

By Satyam KumarJuly 29, 202611 min read

api versioning api deprecation breaking changes semver rest api api design consumer driven contracts pact sunset header backward compatibility api lifecycle expand contract developer experience software architecture api governance 2026

You Can't Un-Ship an API: Versioning, Deprecation, and Getting Consumers Off v1

Frequently Asked Questions

Compartir este artículo

Twitter LinkedIn WhatsApp

Satyam Kumar

Founder & AI Architect, AppScale LLP

Arquitecto de IA y Cloud. Ayudando a equipos a construir sistemas que escalan a millones.

LinkedIn GitHub

You Can't Un-Ship an API: Versioning, Deprecation, and Getting Consumers Off v1

Frequently Asked Questions

Compartir este artículo

Comments

Leave a comment