How to solve your API versioning challenges

How can improvement be bad? The digital world is all about failing fast and continuous improvement. Customers come first, and to delight your customer you need to bring them the latest and greatest version of your product. What happens when your customers, the people who you want to delight, want stability? APIs (Application Programming Interfaces) provide users with superpowers for their business. Whether they are used to display information, add functionality to a product or service, integrate payment, or allow for advanced communication, APIs are critical to running most businesses. 

‍

The added benefit of APIs is that businesses don’t need to create their own. Creating APIs internally can be a long, complex, and expensive process. Not to mention how difficult it is to hire people with the necessary skill sets. More than that, outsourced APIs can be updated to include the latest and greatest functionality. APIs provide value that previously was only available for large companies. However, there is a risk to outsourcing APIs. What happens when they stop working? While there is a small chance an API provider could go out of business or have technical challenges, even the most secure API providers can break an API connection by making an update.  
‍

When it comes to APIs, change is made through versioning. New API versions can bring new functionality, improvements, and fixes to your API. At the same time, these new versions can create complexity and work for your customers. So how do you continuously improve without causing chaos for your customers? In this blog, we’ll take a look at what API versioning is exactly. We’ll outline the challenges with API versioning. Finally, we’ll look at how Blobr helps you to overcome these challenges. 

‍

What is API Versioning?

API versioning is necessary to progress and iterate on an API. It’s impossible to know everything before going live with a new API. This is especially true when you get feedback from customers. Versions will allow you to evolve your API and customers to enjoy upgrades. API versioning is how API products can be updated in a transparent way. It should support clear communication of what changes have been made so consumers understand both the impact and benefit. The version will communicate what is different from earlier forms of the product. 

‍

It is possible to change your API without creating a new version. The only time a new version is critical is when there is a breaking change. Some examples of breaking changes are when an endpoint is removed or there is a change to the endpoint structure. They can also happen when there is a format change or change in the request or response type. 

‍

API versioning challenges

Unfortunately, there is a compromise between making improvements to an API and the cost to customers updating their API, and to the API owners in communicating and maintaining previous versions. 

1. Release timing 

The first rule of API versioning is don’t do it unless you absolutely have to. The only time you have to create a new version is with breaking changes. However, it can be tempting to delay releasing the new version so you can make as many changes as possible. Adding new functionality and fixing bugs may be delayed while you wait until you need to make a breaking change. This slows down the release of improvements. However, if you are able to make smaller, more frequent releases you then need to maintain more versions and documentation. 

2. Identifying customers impacted by changes 

Part of API versioning is deciding at which level to make the change. Will the entire API be updated or will it be a particular set of endpoints or even a single endpoint? More often than not, API providers don't know which customer is using which part of the API. The more granular the change, the harder it can be to identify which customers will be impacted. If the provider doesn’t know who is impacted, the burden falls on the customers. They need to remember exactly which endpoint they’ve used. If they miss any changes then their API is at risk of breaking which could have a significant impact on their business. 

3. Communication with customers  

It is critical that you can communicate with customers so they know exactly what to expect and the magnitude of the change. Due to the lack of clarity on which customer is using what API, this is difficult to do. Most API providers instead release long-to-read API documents. Again this puts the burden on customers to work out what changes they need to make. The customers are not only at risk of missing breaking changes, they also have to take time out from other critical or value-add work to understand the documentation. In the worst cases, API providers don’t have communication channels set up. Some API providers may only have their customer's IP address with no contact details by which to update them of the change. 

4. Maintaining API versions 

API providers don’t know who is consuming what, and they are unable to clearly communicate changes. This means it can be hard to decide on which versions to maintain and when you deprecate your endpoints. Having multiple versions means maintaining additional documentation which leads to more maintenance. 

‍

How to overcome API versioning challenges with Blobr

Until now, the gold standard for companies has been a robust versioning strategy. An API versioning strategy entails predetermined naming conventions, release schedules, and future-proofed documentation. The problem with an API versioning strategy is that it needs to be determined upfront before you’ve launched your API. It is time-intensive and complex in its own right. Many companies have been so overwhelmed by their API versioning strategy that they put it off altogether. 
‍

Blobr has come up with a far more robust approach. The Blobr API platform has a built-in versioning strategy that doesn’t require a committee. Blobr removes this work by building the process into the platform. When you upload an API to Blobr it will be treated like a product. An API can be used for multiple API products and each API product can have a different set of endpoints. Each API product can be used by different customers. Blobr will track which endpoints are being used by who. When you update to a new API version, Blobr can compare what has changed, and who is impacted and even guide the customers through step-by-step communication on what they need to change. 

You will decide if you want the communication to be sent automatically to the end-users. This will make the experience personalized to your customer's needs. Customers will receive personalized changelogs so that they know what has changed in the API products they're consuming. This will decrease the risk of errors for the end-users of the API. Blobr even takes care of the endpoint deprecation by maintaining historic versions of the API documentation. Some breaking changes that you are afraid about for your end-users? Don't worry, you have the option of putting your previous products as private so that users keep consuming those. In parallel, you can create brand new products for new subscribers with the latest version of your API! That's as easy as it looks like!

Blobr is built for API versioning. This means you don’t need to force-fit a versioning strategy into a tool that’s meant for something else. Tools that are not fit for purpose can create additional overhead and even cause unforeseen problems. Now it’s possible to delight your customers by improving your API, without the headache of a complex versioning strategy. Simply upload your API product, when you’re ready to make a change, let Blobr take care of your customers.