sommai - Fotolia

Get started Bring yourself up to speed with our introductory content.

Get a grip! How to handle API versioning decisions

It's rare to nail an API on the first try, making API versioning an important, almost inevitable task.

Service interfaces inevitably change over time. Despite much effort and research, it's difficult to create the perfect interface with version 1.0. Fortunately, it's not difficult to handle the inevitable API versioning decisions that must be made.

API versioning is more of a process problem than a technical one. From a technical standpoint, versioning is straightforward. It needs to be determined whether changes result in a backward-compatible interface. A backward-compatible interface is one where messages still work when coming into an updated API based on the previous version, and response messages from the API should still work when sent back. The term should is used because API consumer actions with response messages can't be controlled.

Normally, the following changes to a request are considered backward compatible:

  • Adding endpoints (e.g., a new REST resource)
  • Adding operations to an existing endpoint (e.g., when using SOAP)
  • Adding optional fields to the request interfaces
  • Changing a mandatory field to optional in an existing request interface
  • Adding fields to a response (whether optional or not)

Typically, the following changes to a request are not considered backward compatible:

  • Adding a new mandatory field to the request interface
  • Making a previously optional field in the request mandatory
  • Removing fields from the request or response (as opposed to making it optional)
  • Making a previously required response field optional
  • Changing the structure or relationship between fields (e.g., making an existing field a child of some other field) in either the request or response

If an interface is backward compatible, it may be best to make changes in place. Existing consumers should continue to work as is; why make work for them if it's not necessary? Why create the potential for running multiple versions in production if they're not needed?

Decisions need to be made if the new interface is not backward compatible. The easiest approach is to create a new endpoint, such as adding a version identifier in the URL. Existing endpoints can be kept, but only if something in the request can clearly indicate the version expected. For example, a custom HTTP header can be used to always specify the version number associated with the message, and then you can rely on the implementation to route the request accordingly.

This is where an API management system or networking infrastructure comes into play. A gateway is a common feature of most (if not all) API management platforms. The gateway should be where the version and route to the appropriate API implementation are determined. A common challenge, however, is that version 1.0 may not have leveraged a router, so now a spot to insert a router into the mix needs to be found. In most cases, this can be done without changing the endpoint visible to the consumer; but depending on how the API is architected, it could be a complex change.

Using transformation for API versioning

Transformation is of value only when you're getting rid of an older implementation. If you're running old implementations, simply route the request to the correct one. However, once an old implementation is turned off, the only choices are to reject the request or transform the request into something a more recent version can handle.

Transformation can handle only a small subset of the cases. A mandatory field can't be added that isn't there with a transformation. However, most situations can be addressed where the necessary information is there but it's not in the right structure or format. It must be decided whether an old implementation should be run.

If an old implementation is run, it can be good for an API's existing consumers, who aren't forced to make changes unless a new capability or information is needed. On the downside, running an old implementation is more costly. The more versions supported, the more complicated the gateway logic will be. It also sets a precedent that APIs are never turned off.

Every situation is different, and how they're handled comes back to the point of the second article in this series: Know your consumer. If you need to bend over backwards when you're dealing with customers, you may have to do everything possible to avoid making them change. If customers have good maintenance practices and make regular updates that encompass both new features and upkeep functions, then retiring old versions may be more palatable to them.

This is also why a solid consumer portal should be a fundamental part of an API management strategy and part of evaluation criteria for an API management solution. How often do customers review API documentation, release notes and sample code? How many make it a regular habit? An API management offering can be a key tool for communicating with customers.

The four articles in this series on API design, along with the previous series on API management tool capabilities, offer solid best practices for getting APIs off on the right foot and for making sound decisions throughout their lifecycle.

About the author:
Todd Biske is an enterprise architect with a Fortune 50 company in the St. Louis metro area. He has had architecture experience in many different verticals, including healthcare, financial services, publishing and manufacturing, over the course of his 20-year career.

Follow us on Twitter @SearchSOA and like us on Facebook.

Next Steps

Learn about using the Semantic Versioning specification for API versioning

This was last published in December 2014

Dig Deeper on API management strategy

Join the conversation


Send me notifications when other members comment.

Please create a username to comment.

How good are you at making API versioning decisions?
Where decisions regarding API decisions are concerned I rend to drag my feet a bit as I am not the best in working through the variances of the API versioning technology. Sifting through the options, which include SOAP, Hypermedia, REST and others is all a bit confusing to me and that makes my decisions difficult. Typically I consult with the IT staff of my enterprise to see where they would direct the API decisions.
I think we all tend to drag our feet a bit when it comes to working with something we aren't comfortable with, Carol. Sounds like you do what makes the most sense in your situation - seek guidance!
Versioning of an API, I think depends a lot upon whether its a public or a private API.  I think most developers have no trouble updating a private API that their software can be updated to handle right away, whereas with public APIs, there then becomes this 'fear' of introducing a change without adequate customer communication.

My advice would be to establish a good mechanism to communicate with your customers if you version a public API.

As for SOAP, HyperMedia, and Rest... I would say those aren't versions, they are 'styles' or types of API systems.  (Versioning actually implies more about what you do when a feature in an API needs extension or modification.)
SOAP, REST, etc. are definitely not versioning schemes, as you suggest. The only time versioning should ever be an issue is when you make a change that is incompatible with the current interface. If ithe change can be backward compatible, then there should be no issues. The only time those stiuations become an issue is when you break the service with a change that should be backward compatible.

As you suggest, I believe transparency is always the best option. Fully communicate changes, regardless of whether they are backward compatible or not. At the same time, don't let your customers control the versioning decision, otherwise you'll wind up with lots of versions in production.

As for public or private, private situations are just as bad as public ones if you're dealing with a large enterprise. You have the same issues with competing schedules, funding challenges, etc. that you do with a public API.