API versioning is a tricky subject to approach due in large part to the varying sentiments surrounding it. There's no doubt that versioning needs to occur, but how those changes are implemented…well, that's where the debate comes in.
Even experts get it wrong sometimes, but don't worry—we've got you covered with this ultimate guide.
What is API Versioning?
API designers have a very symbiotic relationship with developers. The fastest way to disrupt this delicate balance is to roll out a new version.
But what exactly is API versioning, and why does this create such a disturbance?
API versioning is a way of differentiating points in time where the API changes in a way that requires the consumers of the API to modify their application.
To put it simply, it's a way for API designers to provide new features, improve the existing functions, or fix bugs without having to develop a whole new product.
You start off with v1 of your API. Once you make changes to the API that require developers to modify their applications to keep everything running, that’s when you release v2.
Oftentimes, when new API versions are released, the old ones will stay active for some time, providing developers with enough time to make changes. However, if the development changes aren’t made, the old version of the API can cause breaking changes.
Breaking changes occur when an alteration in one part of the software system (an obsolete API version, for example) causes other system components to fail. Not only does this leave developers pouring through hours of code to find the error, but it also causes a break in your contract.
Inevitably, your APIs will eventually outgrow their original scope and need to be changed in some way, but breaking changes are the key in most versioning strategies that determine that a new version is needed.
Learning how, when, and why you should version helps you build an effective versioning strategy that you can clearly communicate to developers, maintaining a healthy relationship with your users and partners.
When Should You Version APIs?
When making any version change to your API, be sure that you have a clear understanding of what is required for this type of update. Your clients rely on the functionality provided by previous versions and may not update their applications when you release a new version.
To flip the switch with as few disruptions as possible, you need to know the three categories for versioning: major, minor, and patches.
Major Version Changes
Major versioning changes are ones that implement a breaking change and require mandatory adjustments for new and existing clients. In most API versioning plans, only the major version number is included in the change, as that indicates when a breaking change has occurred. Examples of this include:
Field or route changes, including removals and renaming
Payload changes
Removing endpoints to fix HTTP design
Minor/Patch Version Changes
Sometimes you may be able to add patches or minor changes in your API without affecting any existing customers. Minor changes, including new features, methods, or resources, can be ignored by existing consumers who don't want to utilize them.
Documentation updates such as fixing typos are typically done through a patching process.
What Are the Most Common API Versioning Schemes?
API management can be difficult and time-consuming, but they are the best way to transition new features and depreciate others. To handle this process, version your API using one of four strategies outlined below.
URI Path
This is the most commonly used (and arguably the most effective) type of API versioning. It is where you include the version in the URL path itself.
For example: https://apiexample.com/api/v1/categories
Pro: Easy to use and doesn't require developer tools. Caching strategies will benefit from this approach since most browsers and proxy servers will be able to cache the response without additional effort.
Con: It's easy for this strategy to get out-of-date and lead to multiple versions claiming ownership over certain pieces or even entire endpoints—which could cause issues with caching on your website. Additionally, this versioning method violates one of Roy Thomas Fielding’s RESTful principles (one resource for one endpoint).
Query String Parameter
This approach lets you specify the API version as a query variable, which is quite effective.
For example: https://apiexample.com/api/categories?v=1.1
Pro: This approach is not only easy to implement, but it also makes updating your API the simplest process possible. Additionally, you can set the newest version to the default unless another endpoint is specified.
Con: Like URI Path versioning, this breaks permalinks and is not RESTful complaint.
Custom Headers
The idea of customer headers is that it allows developers to version APIs by including a custom header field with each release.
For example: curl -H “accepts-version: v1”
https://apiexample.com/api/categories
Pro: This technique does not add filler to the URI. Sub-versions can easily be added as customer headers.
Con: Versioning multiple resources with this technique leads to difficult configuration management. This tactic is also difficult to cache either in the browser or proxy server since they typically require custom code to look at the custom header and include it in the cache key generation.
Content Negotiation
Using a content negotiation approach to version individual resources instead of the entire API is a great way for API developers to keep their codebase clean, offering more granular control and reducing the overall size of the update.
For example: GET https://apiexample.com/api/categories
Accept: application/vnd.exmaple.api+json;version=2
Pro: Similar to custom headers, this allows you to customize specific resources, reducing URI filler. This also doesn’t break matching document metadata types that are fairly standard and pre-defined.
Con: Developer tools are needed to explore all versions, and they may distort HTTP headers' purpose, resulting in difficult management for clients. Again, like the custom headers, calls made using the headers are more difficult to cache either in the browser or proxy server.
How to Build a Successful API Version Strategy
Versioning strategies are an essential part of API design that can ensure your users know what they're getting with each request. They also help you keep track and control updates, which is especially important for maintaining high standards for quality services.
The last thing you want to do is create confusion or frustration for your API consumers. Remember, we want to keep that symbiotic relationship flourishing. So how do you build an effective API version strategy?
There's really no one-size-fits-all approach as every business has differing needs and goals. However, here are a few integral steps you need to take to ensure your strategy will benefit you and the developers who use your APIs:
Establish your versioning scheme and stick to it! While you might face internal pushback about which scheme works best, you need to choose one and use it consistently. This makes it easier for developers to implement changes.
Communicate how you plan to transition versions. To maintain a successful versioning strategy, you need to establish your rules for implementation. How long will you let your older versions remain active? Will you let versions exist side-by-side?
Thoroughly document and document some more. Provide a roadmap for your users where you set release schedules and establish how you will document new features, improvements, and/or fixes. This allows for more transparency and less confusion surrounding your versioning strategy.
API Versioning Best Practices
Developing an API version strategy should be something you start with. Trying to retrofit one into your API program at a later date is not ideal.
As you develop your API version strategy, you should consider the following best practices:
Use a clear naming convention and don't choose numbers arbitrarily. If you start with v1, don’t change that to 2.1 on your next release.
Set a timeline for deprecated versions or allow side-by-side APIs. Carefully consider the number of developers using your older version, how much traffic they receive, and how long your API has been active when considering the length of time you wish to allocate for transitioning before determining a deprecation date.
Have clear, detailed documentation establishing your versioning guidelines, keep them updated, and don’t assume your users will anticipate changes. When in doubt, document it!
Make additions backward-compatible. This allows clients to seamlessly work with both older and newer versions of your APIs.
Automate security with your APIs. You can rest easy knowing that your API is protected with automation. Not only does it protect you from intruders, but it also helps to save time and money by cutting down on unnecessary support costs associated with manual processes.
Deploy an API portal. API portals are an invaluable tool when it comes to managing your API versioning efforts. They gather all of the APIs into one place, helping you easily identify which versions are currently installed on any given system and making it easier for developers to update them when new ones come out.
We get it. Managing APIs is difficult enough on its own–let alone governing multiple versions. Using an API portal powered by Apiboost lets you easily keep track of your internal and external APIs and drastically streamline your versioning strategy.
This means that it is easy for users to manage which version they're using when making requests—giving them peace of mind knowing there won't be any surprises down the line.
If you want to learn more about how to make API versioning a breeze with API portals, reach out to one of our API specialists.
