Whether you have a single API product or you manage multiple APIs across business lines, one thing is common: having an API versioning strategy is important.
In a previous API Expertise article, I outlined common strategies available to API providers. But a common question remains – how do I know when I need to release a new version of my API?
In this follow-up article I will answer this question by discussing the differences between API versions and revisions, including how understanding the difference guides provide on when and how to version their API.
API Versioning: From negative impact to consumer churn
Before we deep dive into this discussion, it is important to recognise the negative impact that a new API version can have on your consumers. When you create a new version of an API, you are telling your API consumers that they have to do some work. Code needs to be changed, and integrations need to be retested. Your API re-design becomes the consumer’s problem.
When the number of API consumers are small (or zero), or when the consumers are internal and you are able to coordinate the API changes easily, then the impact can be minimized. Yet, any change required by an API consumer costs time and effort. As a result, creating a new version of your API should be a last resort.
API versioning has an even greater impact to your business. When customers are integrated with your API, the likelihood of churn is reduced as the perceived value and sunk cost concerns increase. When you version your API, customers must once again make a commitment to your product. Code changes are required to keep up with the latest version. Bottom line: you are creating an opportunity for your customers to move their business elsewhere.
Versions vs. Revisions
Darrel Miller recently presented on how to avoid breaking changes at the 2017 API Strategy and Practice Conference in Portland. His talk demonstrated how Microsoft has chosen to approach the problem: differentiate between API versions that create breaking changes for your consumers, and revisions to your API that improve but don’t disrupt your existing consumers:
In his talk, he outlined two definitions that are sometimes thought of as synonymous: Versions and Revisions. Let’s explore each one to better understand how we can better manage our API versioning strategy.
API versions (consumers choose): Identifies a grouped set of API endpoints and definitions. Versions may be numbers or strings (e.g. v1 or 2017-01-14). Each version of an API is often treated as a separate product with differing behaviors and capabilities. API consumers opt into a specific version and write code against that version. They only migrate to a new version when they are ready, which may be a long time after the new version is released, or perhaps never.
API revisions (providers choose): Identifies an internal change that should have no negative impact to your API consumers. Revisions should be transparent to the API consumer, as consumers should be subscribed to a specific version only. Internally, you may release “v1;rev 5”, but to your API consumers they are still using v1.
I found this approach refreshing, as it provides a more pragmatic approach to API versioning while steering clear of semantic versioning that doesn’t necessarily map directly to HTTP-based APIs. Some of my clients use this technique, using terms such as major and minor version in place of version and revision, respectively (e.g. v1.1, v1.2, v1.3, etc).
Applying versions and revisions to your versioning strategy
Let’s apply this understanding into three API versioning strategies that you can choose to put into practice.
Option 1: Versions with many revisions: This is one of the most common options that I have seen put into practice, as it allows APIs to evolve over time without a breaking change. The API provider adds new fields to payload or even entirely new endpoints or resources to an existing API. Since these changes avoid a change that could disrupt existing API consumers, the API is given an internal revision number, e.g. v1.2. Consumers are upgraded to the latest revision once it is deemed stable. When breaking changes are required the version number is increased, resulting in a brand new API product that must be marketed to existing customers using the previous version.
Option 2: Versions with only one revision: Perhaps less common, this option allows API providers to ship one version of an API, then immediately move to the next version. This strategy may be useful when you are early in your API design and need to make breaking changes more often. Placing more burden on your API consumers, this strategy is best used when your API consumers are either in-house or able to absorb constant rate of change. Some API providers start here, then move to the “Versions with many revisions” option as the API design starts to change less often.
Option 3: One version, only revisions: For API providers that must assume that their API consumers will rarely or never change their code, e.g. Stripe, this is the wisest choice. The API versioning is handled transparently to the API consumer, with request/response payloads transformed to the current internal version and back again. More work is required by the API provider, but this work is seen as having a positive multiplying effect: API consumers never worry about needing to rework existing integration logic.
I believe that Option 3, “One version, only revisions”, is the best option for most API providers, but it comes with a high cost of maintenance. Many organizations are not ready to take on the burden of supporting and rigorously testing backwards compatibility of API versions that may date back several years. Instead, providers often choose Option 1, placing the burden of upgrading to a new version on the API consumers. The risk is that consumers may opt to move to a different API provider or solve the problem themselves than incur the cost of upgrading, resulting in consumer churn.
In summary
Selecting an API versioning strategy is important, not only for your internal development processes but also for your API consumers and the resulting developer experience.
Be thoughtful about how you plan to manage your API versions, including whether you will require API consumers to upgrade themselves or if you will support backward compatibility of your API changes transparently.
No matter which strategy you select, be sure to clearly document your strategy and the expectations you have of developers as they start to integrate with your API. They will thank you for it.
