API Connect

 View Only

API Versioning – Best Practices (and not so great practices)

By Alan Glickenhouse posted Mon January 29, 2018 02:26 PM

Believing you are not going to have to version an API is like believing you are not going to have to change a baby’s diaper.  Sooner or later you’ll have a pretty stinky API.  Versioning is going to occur.  Better to think about how to handle it than react when it becomes necessary.  In this blog I’ll look at some best practices around versioning for APIs and compare this with some not so great practices.

The Why and What of Versioning

Eventually something is going to happen to cause you to need to modify your API.  Either the needs of the consumers will change, new consumers may add new requirements, or the back-end systems (Systems of Record or SoR) will change and you will need to modify the API to invoke these new or changed system interfaces.  Some examples that might cause a need for a new version include:

  • Expanding geography, language, and currency support

  • Adding new product lines or offerings

  • Handling new versions of SoR packaged applications or SaaS applications

  • Accessing multiple systems from different LoBs or from a merger/acquisition

For these, and many more reasons, your API will eventually change.


What I am not going to do in this blog is enter the debate on how to technically implement the versioning.  Should it be in your URI?  Should it be in your header?  You choose.  Google it, you’ll find all kinds of arguments on both sides.  There does seem to be agreement that major version changes are all that should be indicated.  If an API is not backward compatible, then this is a major version change and needs to be indicated with an updated major version number (i.e. V1 becomes V2).  Backward compatible changes are “releases” and should be point indications within the major version and do not needed to be indicated in the URI or header (i.e. V1.0 becomes V1.1, but only V1 is shown in the URI or header).


There also is universal agreement that creating a backward compatible API is far more desirable than creating an incompatible API.  Let’s define these terms.  Every API has an interface that consumers use and then interfaces that the API uses, unseen by the consumer, to invoke back-end systems, microservices, etc. to perform the desired tasks.  If we can maintain the consumer’s callable interface across API versions then the API is usually backward compatible (although some changes to allowable inputs or returned data could also cause incompatibility).  The consumer can continue to invoke the same interface even if we change our calls to the back-end systems.  However, if we change the consumer’s interface and they need to adjust how they call the API, then it is not backward compatible.


From an API Management tooling perspective (for example, using IBM API Connect), it is possible to migrate consumers forward to new versions of an API without any action on their part assuming the API is backward compatible.  If the API is not backward compatible, API Connect supports running both versions of the API at the same time.  This allows you to notify current consumers to migrate forward to the new API in a specified period.  You can also ensure that any new consumers can only register for the latest version of the API.  Reminders to migrate as the deadline approaches are also supported.


Creating Backward Compatible APIs

As mentioned, backward compatible APIs are desired.  But, how do we achieve backward compatibility when we do not know what will happen in the future?  There is no method that can guarantee you will always have backward compatibility.  But, there are certainly methods that can guarantee that you won’t.  And there are some that work better than others.


Let’s use a Retail Mobile App that consumes APIs as an example to explain this best practice.  Two Retailers are creating Mobile Apps, including a function to “check order status”.  Both retailers have many SoR systems in their enterprise including CRM, ordering, inventory, shipping/logistics and many more.


Retailer #1 built APIs based on the interfaces of each of these SoR systems and made this available to the Mobile App developer to build the function to check order status.  To accomplish this the Mobile App developer invokes the CRM API to get customer information, then the ordering API, inventory API, and finally the logistics API before displaying the result to the customer.


For Retailer #1 the mobile developer makes five (or more) API calls to get the answer to display on the App.  This is five back and forth API calls over the mobile network.  From a versioning perspective if any SoR system is upgraded or there is any other change to the SoR interface, there needs to be an updated version of the API which may have different parameters causing an incompatible change.  The mobile developer must change to invoke this updated version of the API to continue to support the function.


Retailer #2 is not focusing on the SoR systems to identify the API interface, but rather on the needs of the consumer.  This retailer builds one API called “check order status”.  It is determined that the mobile developer should pass in the following input to the API: customer ID (authentication), the order number that they are checking, and their language.  That’s it.  The single API will then invoke the CRM application, ordering application, inventory, and logistics and return the result.


Retailer #2’s Mobile App makes one API call to the enterprise.  The single API then calls the same SoR systems as the five calls for Retailer #1.  If there is an upgrade or other change to one or more of the SoR systems we can change the API to support the new SoR system(s), but the API interface used by the mobile developer remains the same – it is backward compatible.  We can migrate the Mobile App to the updated API release without any change to the Mobile App itself.


Creating APIs that are consumer oriented versus provider oriented has many benefits, including a higher likelihood of backward compatibility.  Having a good versioning strategy and focusing on creating backward compatible APIs can go a long way to ensuring the success of your API initiative.  If your APIs are frequently seen to be non-backward compatible, consumers will believe you do not know what you are doing.  Eventually they will look for other API providers who don’t cause them so much rework.  Planning for backward compatibility allows you to move your implementations forward in a less disruptive manner.


To understand more about IBM’s thoughts on the API Economy visit the IBM API Economy website.  IBM API Connect is IBM’s complete foundation to Create, Run, Manage, and Secure APIs.  You can find more information about IBM API Connect at the API Connect website.  And you can also experience a trial version of API Connect.


If you have questions, please let me know.  Connect with me through comments here or via twitter @Arglick to continue the discussion.