← back to the blog

Excuse me! Do you have a minute to talk about API evolution?

Posted on January 14th, 2019 by Rediana Koçi


If you work in an IT-related field, it is impossible not to have heard about APIs. Even if you may have not used them, you have benefited indirectly from them.  We can simply describe APIs as a means of communication between software applications. To better explain how they work, we can make an analogy with the Apis (Genus of honey bees) role. One of the most important things Apis species do is plants’ pollination. By transporting pollen from one flower to another, they make possible plants reproduction. In API world, plants are software, pollens are request/response between software, and Apis are APIs.

APIs are everywhere. We can say for sure that they are the backbone of the software industry. The main reason for this success is that APIs provide advantages and facilities to both their consumers (software developers) and their producers (companies and institutions that expose their organizational data). Developers that use APIs do not have to start from scratch. By outsourcing some functionality to APIs, they can speed up their work and also can focus more on other specifications of their software. On the other hand, by making available their own API, API providers can increase the customer reach of their brand or can create a new revenue stream by monetizing the APIs.

An API is intended to help make the interaction between providers and consumers more efficient. In an ideal world, the cooperation between API producers and consumers can be described as follows: API producers develop a stable API, providing very detailed and helpful documentation, so consumers use it without difficulties. Further improvements in API code do not affect consumers. In practice, the opposite usually happens: APIs are prone to continuous changes, often backwards incompatible and supported by poor documentation. Facing a lot of pain when upgrading to new versions, or even having a bad experience with how the evolution process happens and is communicated to them, consumers see the evolution as a set of painful changes, rather than a needed phase after which they will have their own benefits. Evolution means improvement, not just random changes. When an API evolves, it provides to its consumers more features, higher performance, it is simpler to use, more secure, error-free, or easier to maintain.

Actually, these are the main reasons that drive API producers to change their code. They are forced to make changes to their API in order to add new features, to make API simpler, to improve maintainability, to fix bugs, to optimize the performance and to improve the security of the API. Everything in the technology world, including software, hardware and other elements of this ecosystem, has their own life cycle. As part of this world, APIs should follow the same pace. 

To meet these ‘requirements’, API producers perform different changes on the API code. Based on the effect that these changes have on API consumers, we can classify them as Non-Breaking Changes (backwards compatible, do not break the API clients) and Breaking Changes (not backwards compatible). Usually, the first ones are done for adding new features, performance optimization, security improvements and sometimes even to fix bugs. Non-Breaking Changes do not directly affect consumers. Their application can still run using the old API version, without changing behaviour. If they want to use new features available or to benefit from the improved aspects of API, they have to upgrade to new API versions.  In the case of Breaking API Changes, the situation appears different. After these changes, client applications using older versions may fail to run or even change behaviour if not updated. Most of these changes are refactorings. However, it is difficult to classify the changes based on the reasons why the changes happen because changes and reasons have many to many relationships. For example, when adding new features to their API, producers package them in separate modules, and the existing clients are expected not to be affected. In fact, before implementing the new features, the producers make changes in the existing packages, moving classes between them, thus resulting in breaking changes for the consumers.     

Breaking changes, as previously mentioned, adversely affect API consumers. If not migrated to the new versions, clients’ applications can fail to run, or even change behaviour. Besides the extra effort that API consumers should put to update their applications with the new changes, the most difficult part to be handled is the way the evolving actions are communicated to them.   API developers do not follow standards when evolving their code. Changes are too frequent, sometimes invasive, without warning and without support documentation. Communication channels used to inform consumers are different. Usually, emails are sent to notify them about the changes. Developers offer different time windows for the deprecation of older versions, and not always perform blackout tests (API shut down in a short time frame). 

API consumers’ applications should not be sacrificed every time changes happen. This does not mean that API consumers are the victims and API producers are the only ones to blame. In the Digital Age that we are living, technology is in an ever-evolving process. The continuous and rapid development of technology should go in parallel with the development and improvement of all the system’s components. The fifth generation of mobile technology (5G) will open the door to numerous data-intensive applications like the Internet of Things (IoT) and Smart Cities. These applications will generate huge data volumes, which get value only if shared in the proper way between them, and also with end users. As a means of communication between applications, APIs play an important role in the whole process. But if the actual constraints and problems in their generation and evolution are not overcome, they can be inconvenient more than helpful. Now more than ever, there is a need for automating the API evolution process.