Deprecation and Sunsetting
What is the difference between sunsetting and deprecating an API?
Sunsetting
Sunsetting is a descriptive term meaning the API is on its way to being deprecated. The API developers let their users know that the API is entering a period of limited support and eventual deprecation, and they should look for a replacement option for their API. Sunsetting is also communicated to users with an HTTP header in API calls.
```yamlSunset = HTTP-date```
You can add a link below the Sunset header too: `Link: https://app.abstractapi.com/api/scrape/tester; rel=â€deprecationâ€; type=â€text/htmlâ€`, to provide API consumers with more information, or an alternative API.
There are two different strategies of sunsetting, _limited support_ and _closure_. Closure is effectively deprecation that shuts off the API, but may provide error code responses. Limited support includes redirect URIs, migration endpoints, and limited API functionality. Whichever strategy you choose should be clearly communicated to your users.
Deprecation
Deprecation means the API is no longer supported, and should no longer be used. A deprecated API is defined by the IETF in the Deprecation HTTP Header, and includes a required header that must precede a deprecated or sunsetting API. For example:
```yamlDeprecation: Sun, 11 Nov 2018 23:59:59 GMT```
or if the date is unknown, `Deprecation:true`. This tells a user, who may not have read the API's documentation that the API is no longer supported. You may want to add a link below, `Link: https://app.abstractapi.com/api/scrape/tester; rel=â€deprecationâ€; type=â€text/htmlâ€` to provide your reasoning for deprecation to customers, and perhaps suggest migration endpoints, or a new alternative to this API.
How to Deprecate Your API
Ideally, you have planned for API sunsetting and deprecation in your API lifecycle, and are prepared to execute your plan. If not, it isn't too late to gather information from your users, examine how your API is used, and communicate to your users that your API will deprecate. Consider all the ways your API might be used, and how it is deployed. It might be available on GitHub, or offered via an API marketplace or gateway. You might have API analytics to measure your API usage and understand how users are engaging with your product and help develop use cases. You might even run API case studies. All of this information can be used to build your deprecation strategy. Your strategy will depend slightly on your deployment, but it will include establishing sunset and deprecation dates, clearly communicating these dates to customers, and executing your well-informed plan.
Technical Considerations
As stated in Deprecation above, the IETF requires a header precede a deprecated or sunsetting API. For example:
```yamlDeprecation: Sun, 11 Nov 2018 23:59:59 GMT```
or if the date is unknown, `Deprecation:true`. We know that users are interacting with your API, so why not tell them in a message you know they'll receive? Include a link below, `Link: https://app.abstractapi.com/api/scrape/tester; rel=â€deprecationâ€; type=â€text/htmlâ€` to provide your reasoning for deprecation to users, and perhaps suggest migration endpoints. This is a good time to point users to your next API product if it solves a similar problem to the API being deprecated. Ideally, you've accumulated goodwill from your users over this API's lifetime, and they will continue using your next product, or perhaps a new version of this API.
Customer Considerations
It's not just important to deprecate your API technically, but to give your customers plenty of notice and deprecation warnings. You might let them know via your API's GitHub repo, your website, and your API marketplace site. Put yourself in your customers' shoes: how much notice, and how much communication, would you want from an API supplier to avoid breaking changes? Remember to update your API documentation and API reference with information about the deprecation's date, API version, endpoint migration, and sunsetting. Keep in mind, your API site might still be heavily trafficked after the API itself is gone, so ensure your documentation is up-to-date and accurate. Communicate clearly with your API's users, so there are no surprises on either side of the interface when the deprecation date arrives.
Conclusion
API deprecation is part business problem, part technical problem, and part customer service problem. Careful planning and good communication will help you establish a strategy, gather information, and communicate the future of your API to your customers. If you do deprecation right, a future release of your API will delight your customers.
