An API is a promise. When a software company exposes an interface that other developers build against, it is committing, implicitly or explicitly, to a certain shape of behavior. Those developers write code that depends on that shape, ship it, and move on. The moment the API provider changes that shape carelessly, every one of those integrations can break, often silently and at the worst possible time. This is why API versioning, the practice of managing change in a published interface, is one of the most consequential and frequently botched aspects of building software that others depend on.
The Fundamental Tension
Every API provider faces an unavoidable tension. On one hand, they need to evolve their API. Requirements change, better designs emerge, mistakes in the original design need correcting, and new capabilities must be added. On the other hand, they have made a promise to existing consumers, who reasonably expect that code which worked yesterday will work tomorrow. Versioning is the set of strategies for navigating between these two needs, evolving the interface without betraying the developers who trusted it.
The central concept that organizes this entire discipline is the distinction between breaking and non-breaking changes. A non-breaking change is one that existing consumers can absorb without modifying their code, such as adding a new optional field to a response or a new endpoint. A breaking change is one that will cause existing integrations to fail, such as removing a field, renaming it, changing its data type, or altering the meaning of an existing value. Understanding this distinction precisely is the foundation of responsible API design, because the entire goal is to make as many changes as possible non-breaking and to handle the unavoidable breaking ones with great care.
Common Versioning Strategies
There are several established approaches to versioning an API, each with tradeoffs, and teams often hold strong opinions about which is best. In practice, the right choice depends on the audience and the nature of the API.
- Putting the version in the URL path, so that consumers call a clearly labeled version of the endpoint. This is highly visible and easy to understand, which is why it is so widely used, though purists argue it conflates the resource with its representation.
- Specifying the version in a request header, which keeps the URLs clean and treats versioning as a concern of how the resource is represented rather than its identity. This is more elegant but less discoverable, since the version is hidden from casual inspection.
- Using a query parameter to indicate the version, a simple approach that sits somewhere between the other two in visibility.
- Date-based versioning, where each version is identified by the date it was released, an approach favored by some large API providers because it communicates clearly when a given behavior was the current one.
The Cost of Maintaining Versions
It is easy to underestimate the operational burden of supporting multiple API versions simultaneously. Each active version is code that must be maintained, tested, secured, and documented. Every bug fix and security patch may need to be applied across all supported versions. Over time, a provider that creates new versions liberally can find itself maintaining a sprawling collection of them, each with its own quirks, draining engineering capacity that could go toward new work.
This is why the most disciplined API teams treat new versions as a last resort rather than a routine response to change. They exhaust every avenue for making a change in a backward-compatible way before introducing a new version. Adding optional fields, introducing new endpoints alongside old ones, and designing responses to be tolerant of unknown fields all allow an API to evolve substantially without ever forcing a version bump. A well-designed API can often go years without a breaking change because it was built from the start to accommodate growth.
Deprecation Done Well
Sometimes a breaking change is genuinely unavoidable, and an old version or field must eventually be retired. How a provider handles this deprecation says a great deal about how much they respect the developers who depend on them. Done carelessly, deprecation is a sudden, unannounced removal that breaks integrations without warning. Done well, it is a gradual, communicative process that gives consumers ample time and clear guidance to migrate.
Responsible deprecation follows a recognizable pattern. The provider announces the deprecation well in advance, often months or longer for widely used functionality. They communicate it through multiple channels, including documentation, email, and runtime signals such as response headers that warn the consumer they are using a deprecated feature. They provide a clear migration guide explaining exactly how to move to the supported alternative. And only after a generous window, during which they may monitor usage to understand who is still affected, do they finally remove the old behavior. The contrast with a surprise removal is stark, and developers remember which kind of provider they are dealing with.
Designing for Change From the Start
The deepest lesson of API versioning is that the best time to think about it is before the first version ships. APIs