Designing Versioned APIs That Age Well

Fractional CTO · Founder of Injuria.ai
APIs are contracts between services. Once a client starts using your API, you've made a promise about its behavior, structure, and endpoints. But products must evolve, and this evolution often requires changing the contract. Unmanaged changes break clients, destroy trust, and can cause catastrophic failures. API versioning is the primary engineering discipline for managing this evolution gracefully. It provides a structured way to introduce breaking changes without disrupting existing users, allowing your API to grow and adapt over many years.[25]
This isn't just a theoretical concern. A mobile app may be unable to function if a server API it depends on changes unexpectedly.[26] A business partner's automated process could fail, halting revenue-critical operations. An API contract is a serious commitment, and versioning is the tool that lets you honor old commitments while making new ones.
What is API Versioning?
API versioning is the practice of managing changes to an API by creating distinct, addressable versions. When a change would break existing clients, a so-called breaking change[1], a new version of the API is released. The old version remains operational for a period of time, giving clients a chance to migrate at their own pace. Non-breaking changes, by contrast, can typically be introduced to the existing API version without issue.
The core mechanism of any versioning strategy involves a simple exchange: the client must indicate which version of the API it wants to use, and the server must use that information to route the request to the correct implementation logic. The three dominant strategies for communicating this version information are through the URI path, through HTTP headers, or with query parameters.
The Three Main Versioning Strategies
Choosing a versioning strategy is one of the first critical decisions in API design.[27] Each method has distinct tradeoffs in terms of REST compliance, ease of use, and tooling compatibility.
1. URI Path Versioning
This is the most common and straightforward method. The API version is placed directly in the URL path.
- Mechanism:
https://api.example.com/v1/users
Clients request a specific version by changing the URL they call. On the server side, this is typically handled by routing requests that start with /v1 to one set of controllers or handlers, and requests that start with /v2 to another.
This approach is popular because it's explicit and simple. A developer can see the version just by looking at the URL, and different API versions can be explored easily in a web browser.[28] Major services like the Google Cloud APIs[2] and the Kubernetes API[3] use this strategy. Caching is also simple, as each version of a resource has a unique Uniform Resource Identifier (URI)[4].
The primary criticism of URI versioning comes from proponents of pure REST[5] architectural style. In his dissertation, Roy Fielding[6] argued that a URI should identify a resource itself, not a specific representation of it. The resource is the conceptual entity (e.g., user 123), while its JSON or XML output is a representation. Putting the version in the URI implies that /v1/users/123 and /v2/users/123 are two different resources, when in fact they are just two different representations of the same resource.
Here's a simplified example using Node.js and Express to route versioned requests:
const express = require('express');
const app = express();
// Router for v1
const v1Router = express.Router();
v1Router.get('/users/:id', (req, res) => {
// Logic to fetch user in the v1 format
res.json({ id: req.params.id, name: 'Old User Name Format' });
});
// Router for v2, where the name field was split
const v2Router = express.Router();
v2Router.get('/users/:id', (req, res) => {
// Logic to fetch user in the v2 format
res.json({
id: req.params.id,
givenName: 'New',
familyName: 'Format'
});
});
// Associate routers with their path prefixes
app.use('/v1', v1Router);
app.use('/v2', v2Router);
app.listen(3000, () => console.log('Server running on port 3000'));
2. Header Versioning
This method moves the version identifier out of the URI and into an HTTP request header. This is often considered the purest RESTful approach because it keeps the URI (/users/123) clean and focused on identifying the resource.
There are two common ways to implement this:
- Custom Header: The client sends a custom header, like
X-Api-Version: 2. - Accept Header: The client uses the standard HTTP
Accept[7] header to request a version-specific media type[8]. For example:Accept: application/vnd.example.v2+json.
Using the Accept header is the mechanism for what's known as content negotiation[9]. The client is "negotiating" with the server for a specific representation of the resource. This adheres closely to the HTTP specification, which defines the Accept header for this exact purpose (RFC 9110[10]). Companies can even register their custom media types with the IANA[11]. GitHub's API[12] is a prominent example of header-based versioning.
The main drawback is that it's less accessible. You can't test different versions by just typing a URL into a browser. It requires a client capable of setting custom headers, like curl or a dedicated API client. This can add a small amount of friction for developers exploring the API for the first time.
Here is an example checking a custom header in Express:
const express = require('express');
const app = express();
app.get('/users/:id', (req, res) => {
const apiVersion = req.get('X-Api-Version');
if (apiVersion === '2') {
res.json({
id: req.params.id,
givenName: 'New',
familyName: 'Format'
});
} else {
// Default to v1 if header is missing or different
res.json({ id: req.params.id, name: 'Old User Name Format' });
}
});
app.listen(3000, () => console.log('Server running on port 3000'));
3. Query Parameter Versioning
This strategy embeds the version information as a query parameter at the end of the URI.
- Mechanism:
https://api.example.com/users?version=1
This approach is simple to implement on both the client and server. Like URI versioning, it has the benefit of being directly accessible from a browser. It's a hybrid that keeps the core path (/users) clean but still clutters the full URI. Amazon S3[13] uses query parameters for object versioning (?versionId=), whereas AWS Query APIs (like EC2 or IAM) use query parameters for actual API versioning (?Version=).
A significant downside relates to caching. Some caching proxies may not be configured to include query parameters in the cache key, potentially serving the wrong version of a resource from the cache. While not as theoretically pure as header versioning, it's often seen as a pragmatic middle ground.
A Deeper Look at Breaking vs. Non-Breaking Changes
Versioning is only necessary for breaking changes. A disciplined approach to API evolution can minimize the need for new versions by favoring non-breaking, additive changes. This philosophy is an extension of Postel's Law[14], which states: "be conservative in what you do, be liberal in what you accept from others." An API should be designed so that clients can gracefully handle additive changes.
Non-Breaking (Additive) Changes:
These changes should not break a well-behaved client. A new version is not required.
- Adding a new field to a JSON response body. Clients should be written to ignore fields they don't recognize.
- Adding a new, optional query parameter to a request. The server should handle its absence gracefully.
- Adding a new API endpoint. This has no effect on existing endpoints.
- Adding a new, optional field to a JSON request body.
- Changing error message text or logging. These are not part of the API contract.
The principle of only making additive changes[15] is the foundation of so-called "versionless" APIs.
Breaking (Subtractive or Modifying) Changes:
These changes will likely break existing clients and require a new API version.
- Removing or renaming a field in a JSON response.
- Changing the data type of an existing field (e.g., integer to string).
- Adding a new required field to a request body.
- Changing an existing field from optional to required.
- Removing or renaming an API endpoint.
- Changing authentication or authorization rules. For example, requiring a new scope for an endpoint that was previously open.
When any of these changes are necessary, it's time to plan a new version.
The Lifecycle of an API Version
Introducing a new version is only the beginning. Managing the transition and eventually retiring old versions is critical for reducing long-term maintenance costs. A typical lifecycle has several phases.[29]
-
Alpha/Beta: A new version (e.g.,
v2) is released to a limited audience for testing and feedback. It's not yet considered stable. -
Active/Stable: The version is publicly available and recommended for all new development. At this point, the previous version (e.g.,
v1) should be moved to a deprecated state. -
Deprecated: The version is still fully functional but is no longer recommended for use. You should actively communicate to its users that they need to migrate to a newer version. The HTTP
Deprecationheader, defined in RFC 9745[16], is a standardized way to signal this. The Deprecation header contains a date indicating when the endpoint was or will be deprecated; the Sunset header (RFC 8594) is used to indicate when the endpoint will be retired. -
Sunset: This is the period leading up to the version's retirement. The
SunsetHTTP header, defined in RFC 8594 (which updated an earlier IETF draft[17]), can be used to announce the exact date and time when the version will be turned off. Communication during this phase is paramount. This includes emails, blog posts, and prominent notices in developer documentation. -
Retired/Decommissioned: The version is no longer active. All requests to its endpoints should be disabled. Instead of a
404 Not Founderror, the more specific410 Gone[18] HTTP status code should be returned. This explicitly tells clients that the resource existed but has been intentionally removed and will not be coming back.
The Real Costs and Tradeoffs: A Decision Lens
Versioning is not free. It introduces significant overhead, and the decision to use it (and how) should be made carefully.
The Cost of Versioning
- Maintenance Overhead: Supporting N versions of an API means potentially N variations of your business logic, data models, and tests. This complexity lives in your codebase, making it harder to reason about, maintain, and refactor.
- Documentation Burden: Your API documentation must be versioned as well. You need to provide clear, accessible docs for every supported version and guide users on how to migrate between them.
- Infrastructure Complexity: Routing rules, monitoring dashboards, and alerting systems must all be version-aware. An outage might only affect
v1whilev2remains healthy, and your systems need to be able to distinguish this. - Client Migration Cost: Forcing your users to migrate to a new version costs them time and money. This can damage business relationships if not handled with care and ample lead time.
The Alternative: The "Versionless" or Evolvable API
Some highly successful APIs, like Stripe's[19], take a different approach. They avoid coarse-grained /vN versions and instead follow a discipline of continuous evolution. Stripe does make breaking changes, but manages them by releasing date-based API versions and pinning accounts to the version available when they signed up.
This isn't truly "versionless." Stripe, for example, versions APIs on a per-account basis, allowing users to upgrade their account's API version through a dashboard when they are ready. This is a form of fine-grained, opt-in versioning.
This approach requires immense discipline. The engineering team must have a deep understanding of what constitutes a breaking change and a culture that forbids shipping them. It is best suited for domains that are relatively stable and where the cost of client churn is very high.
Technologies like GraphQL[20] are designed around this model. A GraphQL schema is intended to evolve[21]. You can add new fields and types to the schema at any time. To remove something, you first mark a field as deprecated. Tooling can then statically analyze client queries to see if any are still using the deprecated field. This provides a clear, data-driven path to removing old features.
A Decision Framework for Leaders
- Who are your clients? If your API is only consumed by a few internal teams you control, you may be able to coordinate breaking changes directly without formal versioning. If you have thousands of external, unknown clients (like a mobile app), a formal versioning and deprecation strategy is essential.
- How fast will your product evolve? A product in its early stages is likely to undergo rapid, fundamental changes. A coarse-grained versioning strategy (
/v1,/v2) is often a good fit here. A mature, stable product might be a candidate for a more disciplined, evolvable API approach. - What is your team's culture and discipline? Can your team realistically adhere to a strict "no breaking changes" policy? If not, a formal versioning strategy provides a necessary safety valve.
Common Misconceptions Corrected
1. "REST requires URI versioning."
This is false. As discussed, many purists argue that URI versioning is the least RESTful approach because it conflates a resource with its representation. Header versioning is technically more compliant with the original REST architectural style.
2. "Versioning is only for REST APIs."
False. Any API that acts as a contract needs a strategy for evolution. gRPC[22] services, for example, are commonly versioned by including a version number in their package name within the .proto file (e.g., package myapp.v1;). The principles of breaking vs. non-breaking changes apply universally. Protocol Buffers[23] have their own explicit rules for how to update a message definition without breaking clients.
3. "You must use Semantic Versioning (SemVer)."
Not necessarily. Semantic Versioning (SemVer)[24] MAJOR.MINOR.PATCH is a specification designed for software libraries, where dependencies are managed by package managers. For web APIs, a simple major version integer (v1, v2) is often sufficient and much more common. The key is simply to have a unique identifier for a set of breaking changes. Using dates (e.g., 2022-10-31) is another valid, if less common, strategy.
Where We Are Today
Despite the theoretical arguments, URI path versioning remains the most popular strategy for public APIs due to its simplicity and explicitness. It's used by a huge number of companies, including Google, Twitter (X), and many others. Header versioning is the choice for those prioritizing REST purity and clean URIs, with GitHub being the canonical example.
Modern web frameworks like FastAPI, ASP.NET Core, and Express make it trivial to implement any of these strategies, so the choice is rarely limited by technology.[28]
The broader trend in API design, particularly in high-evolution environments, is toward evolvable schemas as seen with GraphQL and gRPC. These technologies build the concepts of deprecation and additive change directly into their tooling. This doesn't eliminate the need to think about versioning, but it shifts the focus from large, disruptive version bumps to a continuous, more granular process of schema evolution. For many new systems, this represents the future of managing API change.
Sources (29)
- Microsoft's Definition of a Breaking Change
- Google Cloud API Design Guide on Versioning
- Kubernetes API Versioning Documentation
- Uniform Resource Identifier (URI)
- Representational State Transfer (REST)
- Roy Fielding's Dissertation on REST
- HTTP Accept Header (MDN)
- Media Type (MIME type)
- Content Negotiation (MDN)
- RFC 9110 (HTTP Semantics)
- IANA Media Types Registry
- GitHub API Versioning Documentation
- Amazon S3 API Reference (ListObjects)
- Postel's Law (The Robustness Principle)
- Stripe's Philosophy on Additive Changes
- RFC 8594: The Deprecation and Sunset HTTP Headers
- Original IETF Draft for the Sunset Header
- HTTP 410 Gone Status Code (MDN)
- Stripe's API Versioning Documentation
- GraphQL Official Website
- GraphQL's Guide to Schema Evolution
- gRPC Official Website
- Protocol Buffers Developer Guide (Updating Definitions)
- Semantic Versioning (SemVer) Specification
- Harihara Subramanian J, Anupama Murali, Pethuru Raj, Hands-On RESTful API Design Patterns and Best Practices (Packt Publishing Ltd, 2019)
- Tsvetelina Plummer, Dennis Dubbert, Christopher Preschern, Pattern Languages of Programs, People and Practices (Springer Nature, 2026)
- James Higginbotham, Principles of Web API Design (Addison-Wesley Professional, 2021)
- Marcotte, An Atypical ASP.NET Core 6 Design Patterns Guide (Packt Publishing Ltd, 2022)
- Andrzej Jarzyna, Samir Amzani, RESTful API Design Patterns and Best Practices (Packt Publishing Ltd, 2025)