Deprecation
The HTTP Deprecation response header signals a resource has been or will be deprecated.
Usage
The Deprecation header provides notice to clients about resource deprecation status. Servers include this header to indicate a resource is deprecated, meaning the resource remains functional but is marked for eventual removal or replacement. The header acts as a hint rather than a guarantee, signaling the intent to phase out the resource without changing current behavior.
API providers use Deprecation to communicate versioning transitions, alerting clients to migrate from older endpoints to newer alternatives before removal occurs. The header does not affect resource functionality. Deprecated resources continue operating normally, returning the same responses and maintaining the same behavior as before deprecation.
The header value is a Structured
Field Date in the format
@unix-timestamp, where the integer represents seconds since the Unix
epoch. The timestamp indicates when the resource was or will be deprecated.
When present, the value MUST be a Structured Field
Date.
The Deprecation header is commonly paired with the
Sunset header to communicate both deprecation status and
planned removal date. The Link header with rel="deprecation"
relation type points to documentation explaining the deprecation rationale,
migration path, and replacement options.
Values
@unix-timestamp
A Structured Field Date value indicating when the resource was deprecated.
The format is @ followed by a Unix timestamp integer, such as
@1735689600 (representing 2025-01-01 00:00:00 UTC). Use this when the
deprecation start date is known.
Example
A deprecated API endpoint includes the Deprecation header with a timestamp marking when deprecation began. The resource remains functional and continues serving requests normally despite the deprecation notice.
Deprecation: @1735689600
An endpoint marked for removal combines Deprecation and Sunset headers. The Deprecation header marks the start of the deprecation period using a Unix timestamp, while Sunset specifies the planned removal date when the resource will stop responding.
Deprecation: @1735689600
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
A deprecated resource includes Link headers pointing to migration documentation and the replacement endpoint. Clients follow the links to learn about the deprecation reason and transition plan.
Deprecation: @1735689600
Link: <https://api.example.re/docs/deprecation>; rel="deprecation"
Link: <https://api.example.re/v2/resource>; rel="alternate"
Takeaway
The Deprecation header signals a resource has been or will be deprecated, providing clients with advance notice to plan migration while the resource continues functioning normally.