REST in Peace: A DevOps Guide to Killing an API

We attempt to answer the question "When do you and how do you approach retiring an API?"

a year ago   •   7 min read

By Leigh Wallett

While there are billionaires out there trying to live forever, the rest of us will not.

Warning: this might be the most morbid blog ever written about APIs.

No-one wants to think about the end of life. Even when it comes to APIs. What’s the right amount of time to spend thinking of the end? A lot is written about the beginning. Product strategy, launch, growth and maintenance get plenty of airtime. Retiring an API doesn’t get the same focus.

The trouble is the API birth rate. The the human birth rate is exponential. We’ve just crossed the 8 billion mark. API growth is factorial! Which is even faster than exponential growth. The API pool is only getting bigger. It is also finding new and innovative ways to adapt. The end result could be a messy knotted web of APIs, unless we have good guidance for API end of life.

Let us guide you through what this end of life could look like, including how to kill an API, so that it can REST in peace.

A DevOps Approach to Life and Death

Where does DevOps fit into the picture? DevOps is used for both the development of new software, and the continuous delivery needed to maintain and improve developed software.

As API management has taken off, a new term was created to describe DevOps for APIs. It is APIOps. APIOps specifically focuses on the management and support of APIs and the applications and services that depend on them. This includes monitoring API performance such as the speed, security and quality. This management is essential to understand the health of your API and when it is the right time to retire your API.

API Graveyard vs Swamp

There are many reasons to retire APIs, which we’ll look at in detail next. First let’s cover an overarching challenge with APIs. Their greatest strength could also be their biggest challenge. They are so small and easy to create.

As APIs continue to grow and evolve, they can become increasingly messy and complex. The sheer number of APIs is compounded by the complexity of systems and services they connect. This leads to interdependencies and complex interactions between APIs.

The micro-service approach which breaks applications into smaller, independent components puts a great responsibility on management and maintenance. Technical debt needs to be paid, and versioning and compatibility need to be kept up to date.

It is important for organizations to carefully manage and maintain their APIs in order to avoid these potential issues.

Part of that management is deciding when to retire APIs to reduce complexity. It’s important for companies to neatly bury their APIs so they don’t end up in a messy, uncoordinated swamp.

How to Make API Retirement Easy

As the saying by Milton Keynes goes: In the long run we’re all dead. Death can be dreary to consider, especially at the exciting phase of launching a new product. Unfortunately, the best time to think about the end is at the beginning.

When designing an API, it is important to consider how the API will be managed and maintained over time, including how it can be retired if necessary. Some key architecture considerations can make it easier to retire an API. Here are our top 3 considerations.


Decoupling the API from the underlying system or service it provides access to can make it easier to retire the API without impacting the functionality of the system. This can be achieved through the use of an API gateway or other intermediary layer that separates the API from the underlying implementation.


Implementing versioning for the API can make it easier to retire an older version of the API without impacting users of the newer version. This can help to ensure that users have time to transition to a newer version before the older version is retired.


Comprehensive and up-to-date documentation can make it easier to understand and manage the API, including when it comes time to retire the API. This can include information about the API's dependencies, usage, and any potential impacts of retiring the API.

By planning for API retirement from the beginning, organizations can ensure that their APIs are well-managed and can be retired in a smooth and orderly manner when needed.

Why Retire an API?

Now that we’ve considered the beginning, let’s explore the tell tale signs that your API is approaching it’s end. Here are 5 key considerations to watch for. Your API might have some or all of these concerns. There is no clear cut way to define when it is the right time to retire your API, but with the data below you’ll know you are making a conscious choice on letting your API live or die.

API Usage

The first thing to watch for is API usage. If an API is no longer being used by a significant number of users, it may be less relevant. This can include new innovation and usage. If usage has declined significantly or is not being innovated, it may be time to retire the API.

API Technology Changes and Maintenance Costs

The rate at which technology advances can play a role in the relevance of an API. If an API is built on outdated technology or frameworks, it may be in decline.

Similarly, if an API is built on outdated technology or frameworks, it may be difficult or expensive to maintain. This could be another deciding factor to retire it and invest in a newer, more modern API.

If you have monetised your API there is a broader cost to consider. You need to weigh up the maintenance cost vs the revenue the API is generating. If the API is no longer financially viable, retiring it may be the best option.

API Alternatives

The availability of alternative solutions is another consideration to factor in. Are there other, more modern or effective ways to achieve the same goals as the API? If so, retiring the API and transitioning to a newer solution may be the best course of action.

API Security Concerns

Security is a major concern for API users. A security breach will likely trump all other factors. If data is exposed incorrectly, there is a breach in API access or any other security attack, the best course of action may be to quickly shut down the API.

Change in Business Objectives

Finally, as your business evolves, you APIs will too. Where you may have started with a more open strategy with an API, in time it could make sense to change your API model. This might mean adding in restrictions or changing your monetisation model. Part of your business evolution could lead you to retiring an API you started out with.

How to Retire an API

Retiring an API requires thought and preparation. Once you have made the decision to retire your API, your API customers need to be your primary consideration. Here are 3 steps to follow when retiring an API.


Before retiring an API, it is important to carefully plan the process and consider all of the potential implications and impacts. This may include identifying any dependencies on the API and determining how to transition away from them, as well as communicating with any users of the API to let them know about the planned retirement.


It is important to clearly communicate the plans to retire the API to all relevant stakeholders, including users of the API and any internal teams that may be impacted. This can help to ensure that everyone is aware of the change and can prepare for it.


Once the plan has been developed and communicated, the next step is to implement the retirement of the API. This may involve disabling access to the API, decommissioning any infrastructure or services associated with it, and removing any references to the API in documentation and other materials.

It can be helpful to remove access in phases. This might look like switching off access for a day and then switching it back on. This can highlight if there are any customers or services affected that you did no consider. Taking a phased approach allows you to gently say goodbye to your API.

Your API Life Expectancy Calculator

While there is no life expectancy calculator for APIs, we have something that comes close. The newly released Treblle 2.0 is your 1 stop shop to monitor and manage your APIs. We cover the entire API lifecycle from birth until death do us part.

Treblle can help you plan, communicate and implement your API retirement. It can also provide the key data you need to decide when to retire your API.

Treblle gives you get detailed data on your APIs use with our analytics. We help make that data insightful through our fully customisable dashboards. Plus we have a standard dashboard that shows you your Treblle API Score, this is the perfect way to monitor your APIs health.

With security being a primary concern we give you complete control over the data you send and allow you to mask data before it leaves your server. You can even limit the time we keep data in our system. You no longer need to worry about security risks leading to early API retirement.

With Treblle 2.0 we have features specifically designed to help with the retirement phase of an API. You have the ability to mute or transfer ownership of your projects. You can also preset an expiry date when sharing requests or delete them altogether. All of this is possible with ultimate precision and control across our platform.

Create a Treblle account to try it out for free. Let us take good care of your API from birth to death.

Spread the word

Keep reading