Taking down an API is a delicate operation, because if done incorrectly it can lead to frustrated users, damaged reputations, and even lost business. However with careful planning, decent communication, and a little help from some tooling, you can deprecate an API in a way that respects your users and helps them transition smoothly to alternative solutions.
What is API Deprecation?
API deprecation refers to the process of phasing out an API that is no longer useful or relevant. This happens when an API’s purpose changes due to factors like business pivots, evolving assumptions, or company ownership changes. Since businesses and services often rely on these APIs, deprecation involves giving users advance notice, allowing them time to adapt before the API is fully retired.
When you create an API you might think it's going to last forever, but all software has a lifecycle, and APIs are no different. Eventually an API will outlive its usefulness, perhaps because a startup has pivoted, because the assumptions the API were built upon have changed substantially over time, or even because a business has been acquired by new owners who aren't interested in keeping that API going...
Whatever the reason, seeing as entire businesses, workflows, services, and products are relying on these APIs being available, it's best to give people some warning, and this is basically what API Deprecation means.
Marking an API as deprecated means giving people a bit of time to do something about it instead of pulling the rug out from underneath them immediately.
This article aims to help you through the process of deprecating an API, supporting your users on their path away from using this API, to using another one you've made, or using another API made by somebody else.
Announce the Deprecation Early
Transparency is Key
As soon as you decide to deprecate an API, inform your users. This could be through an official blog post, email newsletter, or a notification within your developer portal. Learn how to communicate API version changes in detail here.
Letting people know as soon as possible can help avoid people launching services and products which rely on that API.
Services and products that have already been launched will at least have as much time as possible to switch to an alternative API, whether that's something you are releasing, or an alternative offering.
Provide Clear Timelines
Clearly communicate the timeline for the deprecation process. Include key dates, such as when the API will be officially deprecated, when support will end, and when the API will be fully retired. HTTP actually offers functionality for this via RFC 8594: Sunset HTTP Header.
Sunset: Mon, 30 Sep 2024 23:59:59 GMT
Your API can now automatically alert people about this, and if they've got networking monitoring tools keeping an eye out for this header (which everyone should do) then they can be automatically alerted that one of their dependencies is about to close down.
There are two libraries around that do this for Sunset in PHP and Ruby:
Reading these headers is one thing, but how do you emit these headers? In a previous life I built rails-sunset to make this simple in Ruby on Rails:
class OldController
sunset DateTime.new(2021, 1, 1)
end
If there's no package, you can directly emit the HTTP headers yourself.
fastify.get('/old', options, function (request, reply) {
reply
.code(200)
.header('Content-Type', 'application/json; charset=utf-8')
.header('Deprecation', 'true')
.header('Sunset', 'Thu, 31 Dec 2020 23:59:59')
.send({ hello: 'world' });
});
Update Your Documentation
Mark the API as Deprecated
Clearly mark the deprecated API in your documentation. This can include adding a "Deprecated" label next to the API endpoints, including a banner or note at the top of the documentation page, and updating any related tutorials or guides. Read more on how to properly document API versioning.
Explain Why
Provide a clear explanation for why the API is being deprecated. Whether it’s due to security vulnerabilities, outdated technology, or better alternatives, users will appreciate understanding the reasoning behind the decision.
Offer a Migration Path
Provide Alternatives
Ensure that users have a clear alternative to the deprecated API. This might be a newer version of the API, or it could be a totally different service altogether.
Turning something off without any tips on where to go is a jerk move, so try and find something appropriate even if its a completely different company, or a competitor, because if you're no longer running a competing API you're no longer a competitor. Of course, if you have a large user-base then its common courtesy to let that company know they're about to get an influx of new users, so talk to them about it first.
Create Migration Guides
Develop detailed migration guides that walk users through the process of switching from the deprecated API to the new alternative. Include code snippets, example requests and responses, and explanations of any differences in functionality.
For example, there was a whole trend of people switching from REST APIs to GraphQL APIs, so you need to show people where the GraphQL API is, showing them how to use the new tooling, and get them up and running with their first requests. Then when the trend of giving up on GraphQL and switching back to REST APIs came in, do the same thing.
If it's a migration to a different company, they can likely help you with the migration guide, so again it's worth talking to them. They'll be happy to sweep up all the business so it's a win for both of you.
"Endpoint Maps" can be a handy way to offer migrations for HTTP APIs, and here is how Twitter did it. They're not a perfect example because they kicked everyone off v1.1 at short notice and forced everyone to start paying "to get rid of the bots" which hasn't worked at all, but this migration guide is a useful example nonetheless.
Communicate Directly with Affected Users
Email Notification
Send direct emails to all users who are actively using the deprecated API. This ensures that they are aware of the upcoming changes, because let's be real, not everyone is actively checking the documentation for an API they integrated with two years ago.
You should have email addresses for anyone who signed up for access tokens or API keys connected to their user account, so you can use those for communicating this change.
In-App Banners
Relying on email communications alone for direct contact is not enough, as those emails might be going to somebody who quit a year ago. Check for bounces, and create a list of active users who have not been directly contacted. You'll need to find another way to communicate with them.
Provide Personalized Support
Offer personalized support to users who may have difficulties with the transition. This could be through a dedicated support channel, live chat, or one-on-one consultations for key clients.
Gradual Phase-out
Graceful Degradation
Implement a phased approach to deprecation.
- Limit new sign-ups for the deprecated API.
- Stop users upgrading plans or using new functionality.
- Deprecate lesser-used endpoints/functionality separately before retiring the API entirely.
This adds a bit more work, but if you can trim the "surface area" of your API that's less code to maintain whilst you try and get people off the rest of it.
Monitor Usage
Use API analytics tools like Treblle to monitor usage during the deprecation period.
If the usage is not going down after a few months, you have a problem, and it could be any combination of these:
- People are not getting the emails or other communications.
- You have not blocked sign-ups, so new usage is replacing outgoing usage.
- People are trapped as there is no alternative, or the alternative looks too complicated to migrate to.
You might want to consider extending the deprecation period, or providing additional support to ensure that users are not caught off guard, starting with the accounts you prioritize (based on whatever metrics you find most important). Learn more about testing API changes.
Once the usage us down to a level you find acceptable (either 0, or X% of previous usage), start turning access tokens off.
Flip the Switch
Once you reach the deprecation date and you're going to turn everything off, start revoking/disabling access tokens for the least active users, free users, and accounts you are confident are now using the new API.
It's worth not just deleting the whole API right off the Internet immediately, because if you have a major customer call you up in a frenzy saying their whole world has come tumbling down it'll be easier to turn their access token back on, than it will be to redeploy everything and make sure it all works properly.
Post-Deprecation Support
Offer Post-Deprecation Support
Even after the API is deprecated, consider offering limited support for a set period. This could include security patches or assistance with migration for users who are still in the process.
It's perfectly reasonable to charge a premium for this if they've had more than enough time to migrate and you're spending too much time and money on it, but this is up to you and depends on the specifics of the relationship.
Archive Documentation
Keep the documentation for the deprecated API accessible for a while, clearly marked as archived. This allows users who need to reference the old API to still access the information they need.
Learn from the Experience
Gather Feedback
After the deprecation process is complete, gather feedback from your users. What went well? What could have been handled better? Use this feedback to improve your process for future deprecations. Check out best practices for API governance.
Update Your Process
Refine your deprecation process based on the lessons learned. Ensure that your team is better prepared for future API deprecations.
Summary
Deprecating an API doesn't have to be a negative experience for your users. By being transparent, providing clear alternatives, and supporting your users through the transition, you can maintain trust and continue to build strong relationships with your developer community. Remember, the goal is not just to retire an old API but to guide your users towards better solutions in a way that respects their time and effort.
