Killing an API endpoint is easy. Killing it without breaking your consumers is the hard part. Most teams announce a deprecation in a blog post, send one email, and then act surprised when integrations break six months later. The clients that broke never read the blog post — but their code reads your HTTP responses on every single request. That's where the deprecation notice belongs.
Two standardized headers let you signal the full lifecycle of an endpoint directly in the response: Deprecation and Sunset. Used together, they turn a silent breaking change into a loud, machine-readable countdown.
The two headers
The Sunset header (RFC 8594) tells clients the date and time after which the resource is expected to stop working. The Deprecation header (an IETF draft, but widely adopted) tells clients that the resource is deprecated now — optionally with the date it became deprecated.
HTTP/1.1 200 OK
