API Versioning Strategy

Definition

An API versioning strategy is the explicit policy for how an interface changes over time: what counts as a breaking change, how versions are expressed (URI path, header, media type or query parameter), how long each version is supported, how deprecation is communicated, and how consumers are migrated. It covers both the mechanism and the contract with consumers — and the second half is the one teams underestimate.

Why It Matters

Every published API creates an obligation. Once an external team, mobile app or partner integrates, the shape of your response is part of their code. Change it carelessly and you break production systems you cannot see. Versioning is how you retain the freedom to evolve while honouring that obligation. Get it wrong in the permissive direction and consumers break; get it wrong in the conservative direction and you accumulate five live versions, each with its own tests, bugs and edge cases, consuming engineering capacity indefinitely.

What Actually Constitutes a Breaking Change

• Removing or renaming a field, endpoint or enum value.
• Changing a field's type, or making an optional request field required.
• Tightening validation, changing default behaviour, or altering error codes consumers branch on.
• Changing pagination, ordering or default page size where clients assumed stability.

Additive changes — new optional fields, new endpoints, new optional parameters — are non-breaking provided consumers tolerate unknown fields. Establishing that tolerance in your own client libraries early is one of the highest-leverage decisions available.

Real-World Example

A payments platform I worked with ran /v1 for four years and shipped a /v2 that reorganised its transaction object properly. Both were maintained, and eighteen months later 71% of traffic was still on /v1 because nothing had forced anyone to move. Every bug fix had to be applied twice, in two differently-shaped codebases, and a subtle divergence in currency rounding between them caused a reconciliation incident that took a week to unpick.

The recovery was procedural rather than technical. They instrumented per-consumer version usage, published a dated sunset for /v1 twelve months out, sent quarterly notices naming the specific endpoints each consumer still called, and offered migration support to the twelve largest integrators. They also introduced a hard internal rule: at most two supported major versions, and a new major version cannot ship until a sunset date for the oldest is published. /v1 retired on schedule, with three consumers needing an emergency extension.

The lesson: the technical mechanism of versioning was never the problem. The absence of an expiry date was.

Practical Lessons Learned

• Nothing migrates without a deadline. Consumers optimise rationally — a version with no sunset date will be used forever.
• Cap supported versions numerically. Two is workable, three is painful, four means a permanent maintenance tax.
• Additive evolution avoids most versioning entirely. Many "we need v2" conversations are really "we want to tidy up" conversations.
• You cannot manage deprecation without usage data per consumer. Aggregate traffic tells you nothing about who to call.
• Publish the breaking-change definition. Ambiguity here produces incidents both ways: unexpected breaks, and paralysis about safe changes.

Expert Tips

• Emit Deprecation and Sunset response headers on retiring versions. Well-behaved clients surface them in logs long before your email reaches the right person.
• Instrument version usage by API key from day one. Retrofitting attribution during a sunset is miserable work.
• Use contract tests in CI so an accidental breaking change fails the build rather than a customer's integration.
• Prefer URI path versioning for public APIs — it is visible in logs, easy to route and easy for consumers to reason about. Header versioning is elegant and consistently harder to debug.
• Ship a migration guide with concrete before/after payloads, not a changelog. Consumers migrate from examples.

Common Mistakes

• Versioning nothing and treating every change as safe until a consumer complains.
• Creating a new major version for changes that could have been additive.
• Announcing deprecation without a dated sunset, so the announcement carries no weight.
• Maintaining old versions by copying the codebase, which guarantees behavioural divergence.
• Assuming internal consumers need less notice than external ones — internal teams have roadmaps too.

Key Takeaways

• Define breaking changes in writing and publish the definition.
• Prefer additive evolution; reserve major versions for genuine restructuring.
• Every version needs a sunset date, or it never retires.
• Cap the number of supported versions at two.
• Instrument usage per consumer, and enforce compatibility with contract tests in CI.

Related Concepts

Pairs with Contract Testing, Schema Change Discipline, Release Notes Discipline, and Zero-Downtime Migration.