KAs with any product lifecycle, a key responsibility for API architects and API product owners is deciding when to sunset or retire a feature or offering. The API lifecycle is no different, but requires careful planning to carry out the deprecation to minimize customer impact. Unlike a packaged solution or module which is more of a black box, APIs enable your customers to build custom functionality which may have requires months of integration work and testing. Without the correct assessment or process, you could prematurely deprecate a critical service causing a storm of support tickets.
This guide walks through the best practices of deprecating and endpoint and how to easily do it with Moesif API Analytics.
Why deprecate anything?
In an ideal world with unlimited budget, an API product is perfectly designed to handle every customer use case and can live on forever.
However, real products are constrained and impacted by ever-changing business requirements and thus need to evolve to meet them.
Thus, a normal course of business is to sunset an API or service that is no longer aligned with today's requirements and objects.
This could be removing a few fields, specific endpoints, or retiring an entire service.
- Cost to maintain the service exceeds revenue If the service is no longer profitable and costs more to maintain than the revenue it brings in for your organization or business unit, you may want to sunset that service.
- Migrating to a new API platform If a re-platform or rewrite is already on your road map, this can be a good time where underutilized features are removed for scope reduction.
- Improve the developer experience and reduce bloat Sometimes you want to refactor your API spec to "make it cleaner" and easier to understand from a customer perspective.
- Pivot in product strategy or business objectives When pivoting product strategy to meet new business objectives you may not have the bandwidth to maintain old use cases not aligned with those objectives.
- Loss of key team members and institutional knowledge If the original owner of the service or feature transitioned out of the company, the cost to ramp a new member up may exceed the value of the feature.
- Legacy features pose a security and compliance risk Maintaining a vulnerable endpoint for legacy support could expose you to unnecessary security or compliance risk. A sunset plan should be in place to move customers to an updated implementation.
- API is inefficient or bug-prone Some APIs may be bug-prone or subject your infrastructure to reliability issues. For example, an export API may not have large adoption, yet consumes the majority of your support tickets or causes outages.
Step by step process to sunset and deprecate APIs
Deprecating an endpoint requires a well-defined process to minimize the disruption to your API consumers, regardless if they are other teams at your organization or revenue-generating customers. This process is sometimes called sunsetting, which unsurprisingly refers to the period just before nightfall where we know night is coming, but not there yet. In engineering terms, sunsetting is the period between when the deprecation is announced to customers to when the feature is permanently turned off.
1. Identify customer impact
First step is to understand the impact by deprecating an endpoint or feature. You should have a good grasp of who is using the soon-to-be-deprecated APIs and how it impacts customers' implementations. At a bare minimum, you should understand what percentage of your customers are actively using the deprecated feature. However, simply measuring counts of API calls is not sufficient. You should have a quantifiable business metric to measure impact such as potential lost dollars in revenue, amount of engineering hours to migrate to an alternative, or similar metric.
How to understand utilization of deprecated API with Moesif
In this example, we are deprecating the v1 of the /reviews endpoint. It's relatively easy to see the impact of this deprecation in two charts. First we want to see API usage broken down by company name. Later in the post, we also show how to understand the revenue impact in dollars.
2. Announce the deprecation plan
Now that you decided you want to move forward with the deprecation, you will need to announce your deprecation (end-of-life) plan to your API customers. This should be published on your project blog, changelog, and also emailed to developers directly.
You should also mark the endpoints as deprecated in any developer docs or API reference that you have. If you're using OpenAPI or Swagger, it's easy to mark a Parameter Object or Operation Object as deprecated by setting deprecated to true
Your timeline should have a couple key dates:
- Deprecation announcement date
- Brownout date and process
- Final shutoff date
Brownout or rolling blackout is a deprecation strategy of blocking access to the deprecated feature for a short duration such as a 15 or 30 minutes to help alert API consumers of the upcoming shutoff.
You'll want to send these emails as soon as possible to start your sunset countdown.
3. Email customers when they use deprecated features
Even though you announce the deprecation via email or blog, not everyone will read the announcement or they brush it off not thinking it's relevant.
This is where providing a personalized customer journey based on their API behavior is critical. Each time a customer uses the deprecated feature, let them know right then. This can be done though a combination of HTTP response headers and behavioral emails (customer lifecycle emails).
How to automatically send deprecation emails using Moesif
To use Moesif to automatically send deprecation warning emails, you need to perform two steps. First, create a saved cohort of users who are still using the deprecated feature. In this example, we are deprecating the /reviews/ endpoint for the v1 version of API, so we create a cohort of all users who accessed reviews at least one time in the last 7 days. We also exclude Enterprise customers who have dedicated account managers.
Once done, the next step is to design an HTML email that is sent to this user cohort. That can be done using the behavioral email editor. We want to remind customers every 14 days as long as they are still a member of the user cohort (i.e. users who have accessed the deprecated API in the last 7 days).
4. Warn customers using HTTP response headers
Even if you send warning emails to every customer in your database, sometimes the person responsible doesn't receive it since the developer's contact information is no longer valid, emails got sent to spam, the developer moved on to a different project or employer, etc. The recommended way to ensure the appropriate developer receives the deprecation notice is by in-app notification. While the first thing you may think of is an in-app portal, not everyone logs into an API provider's dashboard on a regular basis.
We recommend taking Clearbit's approach to API deprecation which involves both adding an X-API-Warn response header.
This can also be intercepted by any client SDKs you have and print to stdout.
How to automatically set HTTP response headers with Moesif
With Moesif, this is relatively painless. You can leverage a similar process of creating a user cohort for customers using the deprecated endpoint. Then, you can use
governance rules to automatically add the X-API-Warn when the customer is using the deprecated /reviews endpoint.
In this case, we do not yet want to block requests, we simply want to add the response header so we leave blocking unchecked. This rule will remain on and add header as long as the customer continues to use the deprecated endpoint.
5. Implement a brownout strategy
You can never over communicate a change that could break a customer's integration such as API deprecation. However, sometimes the developer still does not take action.
One way to semi-force customers to do something is with a brownout or rolling blackout strategy. This strategy turns off access to the feature or service temporarily such as for 15 minutes every two days for a week. This will help trigger any alerts and alarms that your customer may have set.
It's recommended to enforce a brownout when the chance a developer is at a computer is high where they can take action quickly, but end user impact is minimal. For example, you may require a brownout to occur during normal business hours. Yet, if you're providing an e-catering API located within the United States, you probably don't want to turn off your API the hours before lunchtime on the east coast or west coast.
If you expect a large number of support tickets, you can implement a rolling blackout where only select customers at a time are "shut off" rather than everyone just like
a rolling power outage that's planned during very high demand such as during heat waves.
6. Monitor usage to see if safe to deprecate
Now that you executed the majority of your deprecation plan, it's a good idea to analyze how usage of the deprecated endpoint is trending to see if it's safe to follow through with shutting off access permanently. Hopefully by this stage, not many customers are accessing the deprecated endpoints or features. You may have a few stragglers which are
ghost services that are no longer maintained, but it's better to be safe and fully understand who is still using the endpoints.
If the API users are critical customers, you may need to delay your shutoff date by a period to work with those customers. Large customers with complex systems are sometimes the last to migrate. This can be done easily using Moesif's API analytics.
How to understand revenue impact with Moesif
Sometimes it's best to go one step further to understand not only who is using the deprecated endpoint, but also the potential revenue lost. This is dependent on how the API is packaged and priced, but can be done whether API leverages usage based pricing or prepaid customer contracts. In this case, the collective revenue for all customers using v1 of /reviews is broken down by the customer's industry. We can see Software & Services (the largest category) alone represents over 18 million in revenue.
7. Shutoff access to the feature
Now that you've added all the steps to properly sunset the feature, it's time to permanently shut it off. Check one last time to ensure no adjacent services are erroring out due to dependencies that were not realized earlier. Congrats, you correctly went through the steps to sunset an API.
Looking for a complete customer-centric API analytics solution? Check out Moesif!
This article was written by Moesif CEO, Derric Gilling for the Moesif blog.
