What is API Deprecation?
An API is a product, even if it isn't sold for money. Customers rely on an API to solve their problems, and it becomes an intrinsic part of their web service. Thus, like any product, a company should consider the API's lifetime, and how to responsibly sunset and deprecate their API.
What is the difference between sunsetting an API and deprecating it? Deprecation means the API is no longer supported, and should no longer be used. In some cases, it may still operate. 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 to customers, and perhaps suggest a new alternative or migration endpoints.
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.
```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”.
Deprecation Considerations
Similar to API versioning, a company needs to consider its customers when an API is undergoing deprecation. Ideally, they had a long term plan set out already that included some of the following.
- Ensure you actually need a new API. It's a lot to ask of your customers to change to a new API instead of just making a new API version, so make sure it's worth it for functionality.
- Monitor usage of your current API. Reach out to specific users and communicate clearly with them.
- Consider who uses your API based on your [API analytics](what-are-api-analytics.md). If they are giant enterprise users, they'll need more time to migrate than small startups.
- Set an informed deprecation date with the information above.
- Communicate this date clearly and repeatedly to your customers.
- Deprecate your API (you made it this far, didn't you?). For instance, here is how you can deprecate your REST API.
Conclusion
API deprecation and sunsetting are important considerations. Even if you aren't making money off an API, your software could be a fundamental pillar of someone's ecosystem, and to just deprecate it overnight would be disastrous for them. Gather analytics, make your decision, and communicate your intent clearly to your customers, so you can maintain their goodwill when you build your next API.
Frequently Asked Questions
What is API deprecation?
API deprecation means an API is no longer supported and should no longer be used. In some cases the deprecated API may still operate, but it is officially marked as obsolete so users know to move away from it.
What is the difference between API deprecation and API sunsetting?
Sunsetting is the preparatory phase, where an API enters limited support and users are given advance notice to migrate. Deprecation is the final stage, when the API is officially unsupported.
How is a deprecated API communicated to developers?
The IETF defines deprecated APIs through the Deprecation HTTP header. It can carry a specific date, such as Deprecation: Sun, 11 Nov 2018 23:59:59 GMT, or simply Deprecation: true when the date is unknown. An optional Link header can point to more context about the deprecation.
Why do companies deprecate APIs?
An API is treated as a product with a lifecycle, so companies eventually need to retire versions that customers depend on. Deprecation lets them responsibly phase out an API that is being replaced or is no longer maintained.
What are the best practices for deprecating an API?
First verify that a new API is genuinely necessary, since versioning may be enough, then monitor current usage and identify your different user types. Set an informed deprecation date based on that analytics, communicate it clearly and repeatedly, and only then execute the deprecation.
Should API deprecation be treated as just a technical decision?
No. Deprecation should be treated as a customer responsibility issue, not only a technical one. Transparent, repeated communication helps maintain goodwill with the users who depend on the API.
