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.
