API Retirement Without the Pain

Nicolas Sartor

When we reach a certain age, we all start planning our retirement. Or at least, we should do! APIs are no exception. You might retire an API for a number of different reasons, including security concerns, API evolution, and API deprecation. But in every case, you need to plan the API retirement carefully, especially if key customers still need to use your legacy API.

Why retire your API?

There are many different reasons to retire your API. The most common are:

Functional changes. APIs evolve constantly. Sometimes, you can just add new functions to an existing API. But eventually, you will need to release a new version. At this stage, you need to plan how to deprecate the old version.

Consolidation. Some companies support a large number of different APIs. Over time, as these expand and evolve, you may find that it makes sense to merge two APIs into one. 

Architecture changes. You may be switching the API from SOAP to REST or REST to SOAP. In both cases, you will need to retire the old API.

Security issues. Sometimes, serious security issues are found in API frameworks. This triggers a need for rapid changes to APIs.

Lack of success. Some APIs simply fail to gain traction. Rather than continuing to expend resources, it may be better to just retire the API.

Misuse. APIs aren’t always as secure as they should be. Sometimes, companies find other people accessing their APIs and even making use of them in their own products. 

Planning an API retirement

API retirements happen all the time. For instance, Google retires large numbers of APIs each year. Sometimes APIs are retired because they are at the end of their useful life. Other times, an API swaps from using SOAP to REST (or vice versa). A good example here is the upcoming retirement of the NIST SOAP vulnerabilities database API. Yet other APIs are retired because there is a direct replacement. For instance, Microsoft recently announced that the Bing Speech API will be retired in 2021 and that developers should switch over to the Speech Services API. What this shows is that these multinational companies go through a careful process of planning and coordination before retiring an API. 

So, what do you need to think about when you retire your API? Well, we can’t give you a definitive answer because every API will be different. But here are some things you should consider.

Are you replacing the API?

This is probably the most common form of API retirement. It includes releasing new versions and consolidating APIs. 

How are you going to migrate users to the new version/API? 

How will you support users in this process? Typically, this will be through direct communication, such as support tickets, or through better documentation. However, will your existing support systems be able to cope? And exactly what new documentation is needed, and how can you make it easy for users to understand the changes?

What functionality will be deprecated or changed?

If your users have come to rely on a feature, you need to make it as easy as possible to achieve the same thing in your new API. Sometimes, you will be able to overload the call e.g. making the new call a superset of the existing one. However, that isn’t always possible. 

Are you retiring the API completely?

In some ways, this is easier to achieve. After all, you only need to warn people that they won’t be able to use the API after a given date. Or perhaps, you may choose a soft retirement, where the API continues to exist but has no active support. 

Completing the plan

You can now put together a detailed plan and timeline to move users to the new API. Of course, you will need to think about how to inform and educate your users. This may be through public announcements, emails, or additional documentation and warning notices on your website.

A better way to retire API functions

Often, you can find yourself in a situation where you need to retire your API, but you are contractually obliged to provide the service to your users. Typically, this happens when you are undergoing a REST to SOAP transformation or when you need to replace an API for security reasons. But there are many other situations where this can arise. This is where Xapix comes in. More specifically, this is where we can help you avoid the pain of a legacy API shutdown. 

Xapix API translation

Xapix gives you the ability to translate calls between the legacy API and the new API. The user is still able to make the exact same API calls as before, but rather than go straight to the API endpoint, they go through a translation. The output is a call in the correct format for the new API. API responses are then handled in the same way, being translated and mapped from the new API to the old. This approach can even support translation between SOAP and REST APIs and between JSON and XML. Powering all this is the Xapix data orchestration layer. 

To learn more about how Xapix can help with your API transformation, contact our team now.