Deprecation

When an API resource is scheduled for removal, clients need advance notice. The HTTP Deprecation response header provides that signal, marking a resource as deprecated while the resource continues functioning normally.

Table of Contents

Usage
Values
- @unix-timestamp
Example
See also

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 is always 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"

Note

Deprecation signals the resource is marked for phase-out but still functions normally. The Sunset header specifies the date when the resource stops responding entirely. A resource is deprecated first, then sunsetted. Both headers often appear together to communicate the full deprecation timeline.