How to Deal with API Versioning Decisions

By CIOReview | Thursday, September 22, 2016

In the programming world, Application Programming Interfaces (API) are packaged application snippets used by programmers to share a plug-and-playable instance of their program with other developers. However, in spite of considerable efforts, it is difficult to develop a perfect interface the first time around.

Change is the rule of nature, the only thing which is certain to happen in the future, especially in the IT industry. Enterprises look to develop an application using latest technology to meet the changing needs of customers. Developers make the necessary changes and release the product with improvised, upgraded functions and abilities according to the client requirements. The ensuing process of software up gradation and assigning them special identifiers is called versioning.

API Versioning is the foremost priority for developers because failing to fix the bugs of the previous version will lead to angry support calls, miffed customers and sometimes even failure of the application.  The developers should ensure that changes made in the previous API version are there in the updated API. Also all the modifications must be evident in a backward compatible interface, for instance, adding endpoints, modifying the structure and adding a new field to the interface, must be visible. Backward compatibility is the attribute of a product which offers interoperability with the legacy interface.

Dealing with the changes depends on the interface, if the application provides interoperability and if it supports backward compatibility then it would be much easier to modify the application. On the other hand, issues arise when application doesn’t support backward compatibility. If there is a possibility of modification breaking the code in the interface, then those changes should be introduced in the next version.

When the software is handed over to developers to customize, they should test the software and fix the bugs before the software goes into the implementation phase. During the execution phase of the build, latest version should run alongside the old version, offering some time for developers to transfer codes to the new version and discard the old version.

Upgrading the Resources

Usually developers face difficulty while versioning between individual resources and the entire group of resources, while upgrading. Versioning a unit separately might not be wise because it increases complexity and makes it difficult for the developers to use APIs. The wise decision would be to have a single versioning scheme for the entire API to avoid complexity and mitigating the risk associated with version updates.

How Do You Version An API?

One of the common ways of versioning API is by adding version identifiers in the URL. As the version number is evident in the URL, it is straightforward and gives a clear picture about build and release to the customers. Alternate solution to this approach is a custom HTTP header that can be leveraged to give precise information about the version number associated with the request and it is aligned with Representational State Transfer (REST) specification that helps in routing the request accordingly.

Plan the Road Ahead

Just like there is no single perfect solution to any problem, in the same way there are pros and cons in API versioning too. Importantly, versioning the interface will give flexibility to cope up with the future changes.  The best way to handle the changes is to keep the communication between the user and developer transparent. For instance, if the customer wants the developing team to improvise on any feature, there should be a proper communication, and requirements specification must be clear. If the developers are able to predict the changes that they are about to encounter then it can be well addressed to keep the customers happy. At the end of the day, it is all about serving customers well and offering them a better service.