Sunset header (API)
The Sunset HTTP response header (RFC 8594) communicates the date and time when a resource or API version will be decommissioned. Clients that see a Sunset header know exactly when the endpoint they are calling will stop working. It is typically accompanied by a Link header pointing to migration documentation and a Deprecation header (a separate draft RFC) marking the resource as deprecated.
Formula
Example:
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Deprecation: Tue, 01 Jan 2026 00:00:00 GMT
Link: <https://docs.example.com/migration/v2>; rel="successor-version"Why it matters in practice
Most API deprecations are communicated only through documentation and emails — easy to miss for teams that are not actively monitoring. The Sunset header delivers the deprecation deadline directly in every API response, making it impossible for a diligent client to miss. Clients that parse Sunset can automatically log warnings, trigger alerts, or surface deprecation notices in developer dashboards. For platform APIs with many downstream consumers, Sunset headers significantly increase the fraction of consumers who migrate before the deadline.
Common mistakes
- •Setting the Sunset date too soon after announcing deprecation — clients need enough time to test and deploy migrations; minimum 6 months for external APIs.
- •Not monitoring whether consumers are heeding the Sunset signal — continue to track traffic to deprecated endpoints; non-zero traffic at the deadline means consumers have not migrated.