How do the HTTP `Deprecation` and `Sunset` response headers work, what do they carry, and how should a client and a provider each use them?

## The problem they solve Deprecation notices historically lived in blog posts, changelogs and emails to an address that left the company two years ago. The integration itself — the code actually calling you — never learns. These headers move the signal onto the wire, so the running client can see it. ## `Sunset` Defined by RFC 8594. A single HTTP-date in IMF-fixdate form: `Sunset: Wed, 31 Dec 2025 23:59:59 GMT` It means: this resource is expected to become **unresponsive** after that instant. It is a statement of intent, not a guarantee, and it is not a caching directive — it says nothing about response freshness and must not be confused with `Expires`. It can be applied to any resource: a whole API version, one endpoint, or one representation. ## `Deprecation` The companion signal, standardised as RFC 9745 after a long draft life. It marks the resource as deprecated, optionally from a stated date, which may be in the future ("will be deprecated on…") or the past ("has been deprecated since…"). Because it existed as a draft for years, deployed implementations vary in the value format — some emit a bare `true`. Interoperate defensively: treat the header's *presence* as the signal and parse the value best-effort. The two are complementary: `Deprecation` says "stop building on this", `Sunset` says "here is when it stops working". Emitting both, with a sensible gap between them, is the norm. ## `Link` relations Neither header can carry prose. Attach documentation with a `Link` header using `rel="deprecation"` or `rel="sunset"`, pointing at a page that explains what is going away, why, and how to migrate. Some providers also emit a custom `Warning`-style or vendor header carrying a human sentence, which shows up in curl output and developer consoles. ## Provider practice Emit the headers from an edge filter or gateway rather than per-controller, so coverage is uniform and no endpoint is forgotten. Start on announcement day, not a week before shutdown. Keep the date **stable or later, never earlier**: pulling a sunset date forward is the fastest way to lose the trust that makes the next deprecation cheap. Record a metric each time you emit them, tagged by client, so you know exactly who has not migrated. Keep serving the endpoint until the date, then return a clear permanent error. ## Client practice Handle them once, centrally, in the HTTP client or SDK: - log at WARN with the endpoint, the date and the `Link` target - emit a counter metric so a dashboard shows deprecated-endpoint usage over time - alert with strong deduplication — once per endpoint per day, not per request, or the signal drowns - optionally fail CI or a synthetic test when a header appears against a production dependency What a client must not do is act automatically: do not switch endpoints, and do not start failing calls before the sunset date. The header is information for humans, delivered by machines. ## Limits They are advisory. Nothing enforces them, most HTTP libraries ignore unknown response headers, and a client that never looks at headers learns nothing. They complement — never replace — email to registered integrators, changelog entries, dashboard banners and, for high-value consumers, a direct conversation.