Every API product manager is ultimately faced with the critical question: “When and how do I version my API?” If you search the web for guidance, you most often find resources on whether to version in the URL or header. While a critical step along the path, there are many factors often ignored by these articles. To remedy this problem, I will discuss some of the things you should consider before you decide to version your API. I’ll then provide some additional resources that may be useful to you along the way.
Let’s all agree: Versioning is not bad
Versioning is sometimes seen as a bad thing and something you should never do. That isn’t the case at all:
“First of all, versioning is acceptable. It is not an admission that your API is wrong or incomplete. Instead, it’s an acknowledgement that your understanding of your API, your use cases, and your customers’ needs will change over time. As your API sees real world use, you will discover use cases you didn’t expect, better approaches to problems you already knew, and even new requirements that didn’t exist when you began the design. This is also known as “developing software.” – A Practical Approach to API Design
New insights can lead to new versions of our API. However, it is important to realise that API versioning isn’t just a technical concern – it is a business concern as well.
Every version is an opportunity for customer churn
API versions aren’t your problem – they are the consumer’s problem. Each time you release a new version, consumers have to decide whether they wish to opt-in or not. The decision is based on the cost vs. the reward. Is the effort to migrate worth the cost it will take to migrate?
This means that a new version can have a positive or negative impact on your business, just like a rewrite of an application can have the same effect to your business. A recent interview with 6 software product rewrites helps to illustrate this point:
“He points out that when you force users to pack up and move, that’s when you’re making “the worst strategic mistake ever”: Because you’re taking your entire recurring customer base and making them think about whether they want to keep using your software or move to something else altogether.” – “Lessons from 6 software rewrite stories”
Masked in every API version discussion is this less-often discussed concern: Every time you make a breaking change and roll out a new version of your API, you risk introducing customer churn as they weight the cost of migration vs. moving to a competitor.
Before you choose to version your API because it doesn’t look exactly like how you view the problem space today, consider how your customers will react to the new version. Not how you think they will react, but how they will honestly react given their busy schedules and backlog of work to get done.
Every version is a new product
Some teams choose not to ever version their API, resulting in API stagnation. This is common when dealing with any kind of product that may introduce a change that could negatively impact their customers.
“They had lots of ideas about how to make the product fundamentally better, but with hundreds of thousands of people building their workflows around Basecamp, every change they made was disruptive to lots and lots of people. The obstacle to change wasn’t a crufty codebase, it was their users.” – “Lessons from 6 software rewrite stories”
However, once you make the decision to introduce a new version, there is more to it than the change from /v1/ to /v2/. Each new major version of your API is a new product. Each new version brings with it new ideas, the potential for new customers, a slow migration of customers to the new version, and also the burden of supporting the previous version.
Versioning too soon and too often
One of the reasons API require versioning is that APIs are officially released too early. While deadlines can have a negative impact on your API design, some teams make the assumption that their API design is ready for production.
When possible, avoid releasing your api too early. Instead, find ways to gain feedback before you freeze your design so that you can make design improvements that could break your consumers once it is released. Here are some techniques that may help you avoid releasing too soon, resulting in the immediate need for a new version:
- Take an API design first approach to gain a better understanding of how the API will be used. The goal of this approach is to seek feedback early, before finalising a specific version of an API. This will allow for changes prior to a production release, along with the reduced likelihood of future breaking changes
- Provide a pre-release of the API, perhaps to a subset of your customers. The intent of an EFT release is to gather feedback on how new, non-breaking changes are designed. e.g. verify resource field naming for a new operation and/or to ensure clarity of design and documentation. The recommended EFT period is typically a few weeks
- Separate your APis into supported and unsupported endpoints to limit the API surface area of each release. This can best be achieved by using distinct URL prefixes such as “/v1/{resource}” for public APIs vs. “/unsupoorted/{resource}” for APIs that are not supported. As APIs stabilise and are ready to be supported, move them under the current API version. This places the risk of breaking API changes for unsupported endpoints onto the customer and helps you avoid supporting APIs that are likely to change in the future.
Separate internal versioning from external impact
Some API providers, such as Stripe, have opted to be backwards compatible over the long term. This decision was driven by the fact that many small businesses have Stripe integrated with their backoffice, with no full-time developers available to adapt to newly released APIs. Here are some details about their API versioning strategy:
At Stripe, we implement versioning with rolling versions that are named with the date they’re released (for example, 2017-05-24). Although backwards-incompatible, each one contains a small set of changes that make incremental upgrades relatively easy so that integrations can stay current.
The first time a user makes an API request, their account is automatically pinned to the most recent version available, and from then on, every API call they make is assigned that version implicitly. This approach guarantees that users don’t accidentally receive a breaking change and makes initial integration less painful by reducing the amount of necessary configuration. Users can override the version of any single request by manually setting the Stripe-Version header, or upgrade their account’s pinned version from Stripe’s dashboard. – “APIs as infrastructure: future-proofing Stripe with versioning”
As noted above, their API versioning is considered a first-class concern for every customer. To enable this level of support, it has been built into their design from the start and helps to avoid deploying many concurrent versions:
If we realise that we made an API design mistake somewhere, we can fix it relatively easily and keep the API’s design more cohesive for new users, while also leaving current users unaffected. It’s also much easier to maintain for us because we only have to build a small compatibility module instead of having to maintain two (or more) completely divergent major API versions. – Reddit comment
Check out the complete article if you want to understand the details of how they manage versioning.
Be prepared to support multiple versions
Versioning your API due to breaking changes is common. The only exceptions are:
- You have a direct relationship with every one of your API consumers and they are willing to migrate to the new version immediately
- You choose to adopt an approach similar to Stripe describes, absorbing version changes yourself rather than forcing them upon your customers
- No one is using your API
Unless your API meets one of the following criteria above, you will have to support multiple versions concurrently. You may need to support previous versions of your API for a longer period of time than you would like. It is important to keep that in mind, as it could have a negative impact on your development and support costs.
Wrap-Up
As API providers, we can become focused on standards and strategies around versioning. But as an API provider, you role isn’t to advocate for your API. Your role is to deliver a solution that empowers the API consumers that will use your API. We are advocates for the many developers that will avoid writing their own complete solution by consuming our API. Keeping that in mind, while balancing the technical challenges with the business impact of API versioning, will help you to achieve a balanced approach to your versioning strategy.
Want to learn more on best practice tips & considerations? Then you’ll want to read of our additional resources for guides on when, why and how to approach to API Versioning.
