Get my system design playbook for FREE on newsletter signup:
This post outlines API versioning strategies.
Share this post & I'll send you some rewards for the referrals.
Building application programming interfaces (APIs) is easy.
But keeping them stable and predictable as the system evolves is difficult.
API consumers depend on API contracts, and even a tiny change can break many integrations. For example, renaming a field, changing a response format, or changing an endpoint could stop someone’s production system from working correctly.
Business requirements change, so it’s necessary to communicate the API adjustments clearly.
That’s where versioning comes in. It provides a structured approach for evolving APIs without leaving the API consumers behind.
I want to introduce Irina Dominte as a guest author.
She’s a software architect, Microsoft MVP, with a passion for distributed systems, .NET, and system design.
Check out her blog and social media:
You’ll find her speaking at developer conferences around the world and blogging online.
API Versioning sets guidelines for introducing changes, shows how extensive those changes are, and ensures consumers can transition to new versions at their own pace.
But here’s the catch: just adding a version number in the URL doesn’t automatically prevent all the problems.
I’ve seen many APIs across different domains that expose a /v1/ in their URLs.
They add new data, change property names, change their types, remove fields, and so on. But years later, they run the same version even though the API has changed a lot.
And many APIs end up with v1 in the URL forever because the same organization controls the consumer apps as well.
So why add a version at all?
When different teams at the same company are the API owners and API consumers, version upgrades are “just” code changes. Teams can synchronize deployments, push breaking changes, and update consumers with little risk of breaking changes.
However, when you expose the API publicly and don’t own the consumers, the scenario changes completely. It means you cannot simply break compatibility.
You’re then limited by:
Service Level Agreements (SLA)
Legal contracts
Third-party dependencies
…all of which force you to design carefully and communicate clearly.
It’s better to avoid spending nights answering support calls because someone’s app broke when you changed an API endpoint.
Onward.
Build Real-Time Communication Experiences with Stream (Sponsor)
With Stream’s SDKs for React, React Native, Flutter, iOS, Android, and more, you can add production-ready chat, voice/video calling, activity feeds, and AI moderation to your app—with just a few lines of code. Backed by a global edge network and a generous free Maker plan, start prototyping today and scale to millions.
API as a Contract
It’s helpful to think of APIs as contracts.
The contract describes the shape of the data, the form of the endpoints, and the behavior of the API. The client and the provider both agree to this contract.
However, the owner adds a new field when business requirements change or when they fix a bug. It means that API contracts change.
And versioning is how we say:
Here’s the old contract, still valid.
Here’s the new contract, with improvements.
There are three paths forward as the API evolves:
1. Release a new version in a new location
This means creating /api/v2/orders while keeping /api/v1/orders around.
The users can use the old version as it is. And switch only when they want the new features. This approach is safe and straightforward for clients, but it creates a lot of work for the API owner.
The API owner has to maintain several versions at the same time. For example, fix bugs, apply security updates, or implement features on all supported versions.
Besides, this approach might become expensive and slow down future development.
2. Release a backward-compatible version
In this approach, the API changes in a way that doesn’t break existing clients.
This means additive changes, such as including new fields, optional parameters, or endpoints in a response. As everything works the same way as earlier, consumers don’t have to update anything.
This strategy allows gradual growth but might be limiting when large design shifts are necessary.
3. Break compatibility
In this scenario, the API changes require each client to upgrade.
Although it sounds like the worst option, sometimes it’s unavoidable. For example, there might be a need for a different data model, or a serious security flaw needs to be addressed. Or the original API design had issues they couldn't fix easily.
In reality, we need a mix of all three, based on the change type and its impact.
But before we go further, let’s understand these technical terms first:
Additive versioning
It means additive changes to an API without incrementing its version.
You add new fields, parameters, or endpoints, but never remove or rename anything. It’s easy for consumers because they don’t have to change their integrations.
Explicit versioning
It means acknowledging when a change breaks compatibility.
You create a new version using a URL, header, or parameter. Thus making it possible to see old behavior in one version and new behavior in another.
I’ll walk you through different approaches to explicit versioning of an API, their benefits, and their drawbacks next.
Types of API Versioning
Let’s dive in: