Sunset header

API Design

Meaning

The Sunset HTTP header communicates a future date when an API endpoint or resource will be retired. It addresses the pain point of clients discovering endpoint removal only after a breaking change has already shipped. It is triggered when a maintainer knows the exact removal date of a deprecated endpoint and wants to give clients machine-readable advance notice.

Primary Function

API deprecation signaling

Communicative Purpose

Enables servers to broadcast a planned retirement date so clients can schedule migration before the endpoint disappears.

Pattern

Server emits `Sunset: <rfc1123-date>` response header → client parses date → schedules migration before that date

Função primária

API deprecation signaling

Propósito comunicativo

Enables servers to broadcast a planned retirement date so clients can schedule migration before the endpoint disappears.

Situações de gatilho

API design: announcing retirement of an endpoint with a firm removal date

Contextos

REST APIs, HTTP services, API gateway configurations, public web APIs, microservices

Padrão

Server emits `Sunset: <rfc1123-date>` response header → client parses date → schedules migration before that date

Colocados típicos

Deprecation header
Link header with rel="deprecation"
API versioning
migration guides
breaking change announcements

Substituições comuns

Deprecation header (signals deprecation without a date)
Link header with rel="deprecation" (carries migration URL)
custom X-Sunset header (non-standard variant)

Erros comuns

Confusing Sunset with Deprecation header (Sunset carries a date, Deprecation does not) — clients may ignore the timeline. Omitting the date value — header becomes meaningless. Sending Sunset without a corresponding migration path — clients cannot act on the notice. Using HTTP-date format instead of IMF-fixdate — parsers may reject the value.

Similar / contraste

Deprecation header (boolean deprecation signal, no date), Link header rel="deprecation" (points to migration target), API versioning (orthogonal strategy for coexistence)

Interferências

Coming from older REST conventions: may rely on documentation or email to announce retirements — Sunset header provides a machine-readable timeline that client SDKs can act on automatically.

Família do chunk

Deprecation header
Link header
API versioning
breaking change communication

Nuance

Do not use when the removal date is uncertain or subject to slippage, since a missed date erodes client trust. Performance impact is negligible — it is a single response header. Boundary condition: clients must actually parse and respect the date; many do not, so pairing with a Deprecation header and a Link to migration docs improves real-world uptake.

Efeito pragmático

Lets automated client tooling detect upcoming retirements and trigger migration workflows before breaking changes reach production, reducing emergency patches.

Dica de memória

Sunset header: like posting a 'going out of business' sign with a specific closing date — clients know exactly when to move out, not just that the store is closing.

Upgrade path

Combine Sunset header with Deprecation header and Link header (rel="deprecation") for full deprecation signaling

Frequência: MediumFormulaicidade: FixedPrioridade de aquisição: Recognition firstPrioridade de output: BothTag de espaçamento: Medium-term