Ron Huber

Ron Huber is the CEO and co-founder of Achieve Internet. He's an experienced senior executive with over 15 years managing and leading software teams in the online media, Internet, and software development space.

About the Author


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.