Developer Tools & Open Source

How to Solve API Modification Nightmares

By Special Guest
Brian Pontarelli , CEO at Inversoft
  |  March 08, 2016

Web-based APIs have been around since the early 2000s. However, over the past few years we have seen a dramatic increase in API availability. There are now more than 14,000 APIs listed on the ProgrammableWeb. The API revolution is universal. Industries outside of technology have embraced this as a business model and are experiencing success (i.e. Netflix and Amazon). 

APIs are able to increase companies’ revenue and extend their reach quickly. The downside includes dependence on the API provider and exposure to inevitable changes.

As the API economy continues to skyrocket, developers and providers would be wise to consider these key strategies to minimize the risks that accompany API modifications.

Set Expectations

APIs intrinsically version and deprecate.  That is the nature of software innovation.

A deprecated class or method is described by Oracle (News - Alert) as “no longer important. It is so unimportant, in fact, that you should no longer use it, since it has been superseded and may cease to exist in the future.”

Deprecation is inevitable as APIs continue to expand their reach and evolve with time. If you are an API consumer, it is wise to promptly update your software. Stay current on versions to reduce pain during upgrades and lessen the risk of losing support or the API altogether. When you receive access to API software you don’t own, the reality is you are no longer in control. Developers must set expectations, expect changes, and prepare for down the road costs associated with the lifecycle of software.

On the flip side, API providers must acknowledge this risk and provide information and ample warning for API versioning and deprecation. Providers should deprecate slowly, take time to transition, and work diligently with the customer so that as the API evolves it does not break their existing tools. API release calendars are extremely useful to developers along with early dialogue, direct communication, and planning.

Proper Service Architecture with Common Design Patterns

Loose coupling simplifies the API upgrade process and ultimately saves time and money when APIs break compatibility. 

As an API consumer, it is important to avoid tightly coupling third-party APIs. Instead, build separate service components using well-defined interfaces. In doing so, you can encapsulate the API-specific details to a service implementation.

Decoupling the implementation, upgrading the API, or moving to another API provider will reduce the impact on your total product since the change will be concealed behind your service interface.

API providers should use proper design patterns to upgrade while still offering backward compatibility for clients who will feel the biggest upgrade pains. This will ease the transition for developers.

At this point, API providers should all be using semantic versioning –a simple standard that easily identifies compatibility. This system will ensure dependency nightmares are a thing of the past.


Another option for API consumers is to use an on-premises solution. In this scenario, you no longer rely a cloud hosted API that can be changed at any time by the provider. Instead, you manage your own upgrade timeline and strategy. The API provider can no longer dictate how you spend development time and money. With an on-premises API, the software is downloaded and installed on your servers. You choose when to update or not. Many companies find comfort in running on-premises solutions; they are able to insulate themselves from breakage changes.

While you will always have access to the downloaded API, it is important to note that you still risk losing support if the company changes or goes out of business. You might also be forced to upgrade eventually to maintain your support contract and ensure any bugs found are fixed quickly.

API providers should consider providing a hosted and on-premises solution if they want to support all types of customers.

Minimize Risk

With the growth of APIs and their increased business value, providers are deprecating and versioning their APIs as part of their business model. This can present problems for developers that rely on the API. By setting expectations, decoupling implementation and considering alternative solutions altogether, such as on-premises APIs, developers can regain control and providers can minimize the risks that go hand in hand with API deprecation. 

Brian Pontarelli is CEO at Inversoft

Edited by Maurice Nagle