Deprecation Policy

Every API will eventually be deprecated, so having a plan and communicating the deprecation policy with consumers via a dedicated page makes a lot of sense. This page will help API providers think a little bit about the future, and establish some guard rails and channels for communication with consumers.

Also known as: Sunset Policy, End-of-Life, EOL

Example

- type: DeprecationPolicy
  url: https://developers.example.com/deprecation

Standards

IETF RFC 9745 — The Sunset HTTP Response Header Field
IETF (historic) RFC 8594 — The Sunset HTTP Header Field (obsoleted by RFC 9745)
IETF The Deprecation HTTP Response Header Field (draft-ietf-httpapi-deprecation-header)
IETF RFC 5829 — Link Relation Types for Simple Version Navigation
IETF RFC 8288 — Web Linking
OpenAPI Initiative OpenAPI Specification (deprecated flag)

HTTP Headers

Header	Direction	Spec	Description
`Sunset`	response	RFC 9745	HTTP-date indicating when the resource will become unresponsive.
`Deprecation`	response	draft-ietf-httpapi-deprecation-header	Indicates a resource is deprecated; value is the deprecation date or the token "true".
`Link`	response	RFC 8288	Carries sunset, deprecation, successor-version, and alternate relations pointing to migration targets.

OpenAPI Expression

deprecated (OpenAPI 3.x) — Boolean flag on Operation, Parameter, Schema, or Header objects marking the element as deprecated.
info.x-sunset (Vendor extension) — Common extension for documenting sunset date at the API level.

Link Relations

sunset — RFC 9745 — Points to a policy or document describing the upcoming removal.
deprecation — draft-ietf-httpapi-deprecation-header — Points to documentation about the deprecation.
successor-version — RFC 5829 — Identifies the next version of a versioned resource.
latest-version — RFC 5829
predecessor-version — RFC 5829
alternate — RFC 8288

Governance Rules

oas-operation-deprecated (Spectral built-in) — Deprecated operations should be flagged and ideally include migration guidance.
oas-path-deprecated (Spectral built-in) — Surfaces deprecation across paths so reviewers can plan removal.

Risk & Compliance

Compliance:

SOC 2 CC8.1 — change-management communications to stakeholders
ISO/IEC 27001 A.14 — system acquisition, development, and maintenance lifecycle controls

Security: Long-tail use of deprecated endpoints accumulates known vulnerabilities and unsupported authentication patterns. A clear policy with Sunset + Deprecation headers, telemetry on deprecated traffic, and a documented removal date reduces lingering attack surface.

Tools

Spectral — Linter (Apache-2.0)
oasdiff — Diff / breaking-change detector (Apache-2.0)
openapi-diff (Tufin) — Diff
optic — Change tracking (MIT)

Suggested Metrics

deprecated_endpoint_traffic — Share of traffic still hitting deprecated operations; informs sunset readiness.
time_to_sunset_days — Days remaining between current date and the announced sunset for each deprecated resource.
migration_completion_rate — Fraction of clients/integrations that have moved to the successor version.
sunset_header_coverage — Share of deprecated responses that carry the Sunset header.

Example Implementations

GitHub — API version sunset announced via headers and the changelog.
Stripe — Versioned API with documented behaviour changes and long-tail support.
Google — API deprecation schedule with minimum support windows per product.
Microsoft Graph — Beta-to-v1.0 promotion path with deprecation announcements.