API Best Practices for Feature Deprecation

TL;DR Talk to your users

Most people who write software for a living have one thing in common - they don’t want to be stuck supporting all of the software they've developed forever.

A few areas of the software industry try to use this practice to their favor and go a different direction — operating systems work to be compatible with old software as long as possible. “Linux doesn’t break user-space,” Windows ships with compatible run-modes and macOS even had Rosetta, a software that allowed you to run software created before they switched to Intel CPUs.

Even some cloud providers try to keep deprecation to a minimum so they can always say “we won’t let you down.”

There are multiple reasons why it could be a good idea to stop providing an API feature, but not being a company of the size of Microsoft or Amazon is enough of a reason to stop serving parts of your API at some point in time.

What is deprecation?

Deprecating a feature means that we tell our users that they shouldn’t use this feature anymore because it will be gone sometime in the future.

What questions should we be asking?

When it comes to deprecation, technical people usually think about implementation details:

“How do I mark my field as deprecated in GraphQL?”

“Is there a deprecation header for my REST endpoint?”

While the answers to these questions lead to nice communication tools that allow us to prevent new users of our API to using these deprecated features, the bigger question is often what happens to the existing users.

Will they even check for deprecation message inside the API?

The problem is often that such measures lead to under-communication. _“We announced a new major version and marked some endpoints as deprecated, everyone knows that this can happen, so this should be enough.”

So these are more important questions:

• Who is using the feature?
• How hard is it for us to keep the feature?
• How much are our customers willing to pay to keep it?
• How significant is the impact for us if we keep it vs. get rid of it?
• How fast do we want to remove the feature?
• How much time do our customers need to accommodate the changes?

Who would be affected by the deprecation?

It is crucial to get a feeling for the impact of the deprecation. One way to achieve this is to get the word out as soon as possible.

Write emails, blog articles, GitHub issues, and tweets and see what our users think. We should be in a constant conversation with our users, but when it’s something that could lead to frustration, it’s especially important.

Another way is to use API analytics services like Moesif to find out how much these features are used.

Let’s look at the following screenshot of Moesif API Analytics:

Here we see a stacked bar-chart of our API-endpoints. Every color is a company that uses our API, and the size shows the count of requests that this company has sent to that endpoint in the last 28 days. We can see in one glance which the critical API endpoints are and who is using them.

If we wanted to deprecate the /reviews/reviews endpoint, we see that it’s only used by one company and we could talk to them about our deprecation idea directly.

Often one of the main reasons to deprecate a feature is that no one was using it, so this could even be the first step before asking users what they think.

Talk to the affected before deprecating

Next, we should reach out to the people who are affected. We have the analytics data and can talk to the people who are using the features directly and if we’ve announced a deprecation plan on social media it could be that people who are currently not using the feature speak out because they planned to it in the future.

It could also be that potential customers say that this feature was essential to them for considering our API in the first place.

After the input of the users is gathered, it can be used in conjunction with internal company requirements to plan the deprecation.

Announce the deprecation

The next step is to inform the users that the deprecation is happening.

For many companies that is the first step and they write a blog article and hope everyone affected will read it, but this is not enough!

If we used Moesif API analytics, we can check who is using the feature we want to deprecate. Usually, we have email addresses associated with our user or company accounts, so we can directly send a mail to the feature users, which is probably the most straight forward way.

Writing a blog article, tweeting about, creating GitHub issues, and sending emails to all users isn’t wrong since it shows your users that you care.

Then we can use the techniques given by our type of API to mark the features finally as deprecated.

Also: Don’t forget to update the documentation!

Waking the rest with brownouts

The last way to communicate the deprecation is a brownout.

We wrote emails, announced it on social media and finally marked our endpoints and fields as deprecated.

But if we got a few thousand users, there can always be some users that filter us out as spam, don’t follow us on social media and never check if an API returns deprecation warnings.

To wake them, we can use a technique called brownout. It works as following:

We check for periods in which the deprecated features have low usage. In this periods we disable the features for a few hours or minutes, depending on the usage frequency, and switch them back on.

This can be done one or two months prior to the final shut-down of the feature and lead to spikes in the monitoring of the users.

It’s also important to keep the users who read our emails and social media informed about this, so we won’t be swept by their concerned messages.

Conclusion

Always keep the conversation going.

If we talk to people, they will see us as people too and not just faceless corporations, even if they have a different opinion than us.

It’s essential to get a feeling for what’s happening around us and with our APIs.