Best Practices for Deprecating and Removing an API

Why removing an API the right way is important

A few weeks ago, our alert klaxons started blaring (alert notifications – we don’t really have klaxons, but maybe we should). We had a massive spike in failed background jobs. With the scale of data processing at Instrumental, a few minutes of background jobs is potentially hundreds of millions of data points. Our internal monitoring quickly proved that while our data pipeline was safe, all our API calls to Intercom were failing. Intercom had removed a critical API call we used to manage our customer service and product marketing. Our on-call team was forced to drop everything, and begin writing, testing, and deploying an emergency fix across all our products.

We are enormous fans of Intercom. We use Intercom across all of Expected Behavior’s products (and they are a Gauges customer). We were pretty surprised by the API removal. After discussions with their support team, we discovered the deprecation was announced years ago, and we missed the notifications sent at the time of deprecation. In the time since the announcement, the deprecation warning had been removed from their site so it was difficult to discover what happened when the API disappeared.

We’re in the process of updating some APIs ourselves, so this incident naturally turned into a discussion about how to best deprecate and remove APIs. Intercom did most of their removal wonderfully, but it’s easy to miss a couple steps that can result in immense user frustration. After a lot of internal discussion, here are some guidelines we came up with for doing it correctly:

Ask yourself, do you really need a new API? Must the old one be removed?

Removing an API creates a lot of work for your customers and partners. While the benefits of a new API might be large, does it truly outweigh the cost to your customers? Are there alternatives you can explore? Often, writing a thin layer on top of a new API, to make it resemble the old API, can let you get all the benefits you need without forcing change on your customers.  Sometimes, though, you need to make a big change and get a clean break.

Build and release the new API

This may seem like common-sense, but we’ve seen it cause major problems before: overlapping APIs that don’t operate well together are a recipe for disaster. Use versioning to make sure your APIs can live side by side! Keep the documentation for both API versions available. If it really is a clean break from one to the other, keep them completely separate.  Build and release your new API before deprecating your old one!

Monitor usage of new API vs old API

Make a graph in your monitoring tool showing usage of the new API vs the old API. Monitoring usage helps evaluate when you should begin the removal process. Ideally, you implement this monitoring in a user-specific format so you can see which individual users are using the API.

Pick a removal date

Use your best judgement on selecting a date. If your users are primarily slow-moving enterprise organizations, you might need pick a date a year or two in the future. If you’re working with startups and it’s non-critical, maybe 90 days is good enough. You can always change your mind if usage of the old API is too high, but a date helps your users prioritize this change appropriately.

Inform users of the deprecation and upcoming removal date

Notify your users by both communicating with them directly, and through documentation. Intercom is doing a great job of this with their current API key deprecation.

At a minimum, send your users an email, but you should also update them via Intercom messages, blog posts, and social media. When deprecating an important or highly used API, send a series of emails over several months. However you choose to alert them, users should never be surprised when you remove an API.

Permanently update your documentation with deprecation warnings at the top of the relevant pages for the old API, and maybe even the top of all documentation pages, depending on the importance of the deprecated API.

Monitor for specific users and reach out

As you approach your removal date, setup your API usage monitoring to be user-specific, if you didn’t already do so from the beginning. Then reach out to any user still using the old API. Communicate by both email and Intercom, and warn them of the upcoming API removal. This is the most critical step to ensuring your users aren’t upset about the API removal. It’s the step that caused us the most frustration with the Intercom API removal.

Remove the API

Don’t all the red lines on that pull request feel good?! Bonus points if you respond to old API calls with 410 “Gone” HTTP header and a note about the API removal.

Inform users of the removal

Yes, do it again. Overcommunicate. Send a tweet and write a blog post. If, somehow, any users were surprised by the API removal (as we were), the tweet and blog post help them easily figure out what happened. Don’t make your users dig for an old blog post.

Consider API management services

Definitely optional, but if you want to streamline some of these steps, consider using an API management service to help with communication and change log management. Hitch, Apigee, and 3scale are just some of the many API services we’ve heard of (though we haven’t used these three and are not personally recommending them).

What did we miss?

We think API removal is an aspect of SaaS products that doesn’t get the attention it deserves. We hope this post provides solid and helpful guidelines. Let us know at @Instrumental if you think we missed something or could explain something better!

Note from Intercom

We shared this post with Intercom and they asked to include the following quote:

“We understand the frustration caused by the API removal and appreciate Expected Behavior letting us know. This is an area we take seriously and we’re actively working on ways to improve how we communicate changes like these, such as an upcoming API release schedule, more proactive messaging to users, and more regular updates on our blog.”

We can see they’ve already starting taking these actions. Thanks to Intercom for being awesome!

Instrumental Free Trial

Understanding what's happening with your software is only possible if you monitor it at the code layer. From agents to our metric-based pricing, we’re focused on making it easy to measure your code in real-time. Try Instrumental free for 30 days.