Deprecation general response

What it does

Deprecation signals that a resource, API endpoint, or specific behavior is deprecated — a machine-readable equivalent of a documentation banner or changelog entry, but checkable programmatically by client code or automated monitoring rather than requiring a human to read release notes. It's commonly paired with Sunset (which specifies an exact future removal date) but can also be used on its own, simply flagging deprecation without necessarily committing to a hard removal timeline.

Syntax

Deprecation: true
Deprecation: <HTTP-date>

Two valid forms per the current spec (RFC 9745):

• true — a simple boolean flag, meaning "this is deprecated," without specifying when it became deprecated
• An HTTP-date — the date the resource became deprecated (not when it will be removed — that's what Sunset is for)

Deprecation: Mon, 01 Jan 2026 00:00:00 GMT

How it's used in practice

• Flagging deprecated API versions or endpoints — every response from a deprecated API version includes Deprecation: true (or a specific deprecation date), letting API consumers detect they're using something on its way out without needing to check documentation manually.
• Combined with Sunset for a full deprecation lifecycle — Deprecation marks "this is deprecated as of X," while Sunset marks "this will stop working entirely on Y," giving consumers both the current status and the hard deadline.
• Feature-level deprecation within an otherwise-active API — some APIs use Deprecation on specific response fields or optional behaviors that are being phased out, even while the endpoint itself remains fully supported overall.
• Automated dependency auditing — internal tooling that scans an organization's API usage for deprecated dependencies relies on this header to build an accurate, up-to-date picture of technical debt without requiring manual documentation review.

Common mistakes and gotchas

Using Deprecation without any accompanying migration guidance. Like Sunset, a bare deprecation flag tells consumers something is going away but not what to use instead — pairing with a Link header pointing to migration documentation or a replacement resource makes the signal genuinely actionable.

Setting Deprecation but never actually retiring the resource. If something stays marked Deprecation: true indefinitely with no real plan to remove it, consumers learn to ignore the signal — deprecation headers work best as part of a genuine, followed-through retirement process, not a permanent "eventually, maybe" label.

Confusing the date form with a removal date. The date value in Deprecation represents when the resource became deprecated, not when it will stop working — that distinction belongs to Sunset. Mixing these up in client-side logic (treating a deprecation date as a hard cutoff) can lead to premature or incorrect handling.

Not distinguishing endpoint-level from field-level deprecation clearly. If you're using Deprecation for something more granular than "this whole endpoint is deprecated" (like a single response field), make sure that's clearly communicated elsewhere (documentation, response body annotations), since the header itself doesn't have a standard mechanism for specifying which part of a response is deprecated.

Real-world examples

Simple deprecation flag:

HTTP/1.1 200 OK
Deprecation: true
Link: <https://api.example.com/docs/v2-migration>; rel="deprecation"

Deprecation with a specific date it took effect, plus a future sunset:

HTTP/1.1 200 OK
Deprecation: Mon, 01 Jan 2026 00:00:00 GMT
Sunset: Wed, 01 Jan 2027 00:00:00 GMT
Link: <https://api.example.com/docs/v2-migration>; rel="sunset"

FAQ

What's the difference between Deprecation and Sunset?

Deprecation marks something as deprecated, optionally noting when that deprecation took effect. Sunset specifies exactly when the resource will stop being available entirely. A resource can be deprecated with no sunset date yet announced, or can carry both headers together for a complete lifecycle signal.

Should I use Deprecation: true or a specific date?

A specific date is more informative when you have one (it lets consumers see how long something's been deprecated, which can inform urgency), but true is a reasonable simpler default if you just need a basic flag without committing to precise dating.

Does Deprecation mean the resource will definitely be removed?

Not necessarily with certainty — it signals the resource is deprecated and discouraged from continued use, but doesn't guarantee removal or specify when, unless paired with Sunset. Some deprecated resources persist for extended periods for backward compatibility reasons even without an announced removal date.

How should client code react to a Deprecation header?

At minimum, logging a warning so developers notice the dependency is deprecated is good practice; more sophisticated handling might include surfacing the warning in monitoring/alerting systems, or checking the accompanying Link for migration guidance automatically.

Fun fact

Deprecation (RFC 9745) is a notably recent standardization — finalized years after Sunset (RFC 8594) despite being the conceptually simpler, more general-purpose signal of the two. This ordering reflects how standards bodies sometimes formalize the more specific/urgent use case first (a hard removal date has clearer, more pressing implications) and circle back to standardize the softer, more general signal later, even though in practice most real-world APIs conceptually needed both from the start.