API deprecation, explained
A deprecated feature still works but should not be used for new work. Providers signal deprecation in documentation, changelogs, emails and machine-readable Deprecation headers, and set a removal date with the `Sunset` header.
Effective deprecations measure who still calls the old behavior, run brownouts before the cutoff, and return 410 Gone after it.
Related terms
- Sunset header: The Sunset header (RFC 8594) is an HTTP response header that gives the date after which a resource is expected to stop responding.
- API versioning: API versioning is the practice of exposing multiple versions of an API at once so providers can ship breaking changes while existing clients keep using the version they were built for.
- Breaking change: A breaking change is a change to an API that causes a correctly written client, which worked before, to fail or behave differently without modifying its code.