API Deprecation
API deprecation is a scheduled, communicated retirement of an endpoint, field, or version, with dates, telemetry, and a migration path before removal.
Definition
API deprecation is the lifecycle phase in which a published interface is marked for eventual removal, giving consumers a documented timeline, a replacement contract, and enough signal to migrate before the endpoint stops working.
Context and scope
Use it whenever a public or partner-facing contract must change incompatibly, or when an old version costs more to maintain than the traffic it still earns.
Common misconceptions
- Deprecation means the endpoint is already removed; it is a warning window with a deadline
- Publishing a changelog entry is enough; consumers also need machine-readable signals, telemetry, and direct outreach
- Every deprecated route can be deleted on the announced date regardless of who still calls it
Anti-patterns
- Announcing removal only in a blog post that no integration owner reads
- Setting a sunset date without measuring which API keys still call the old route
- Keeping deprecated versions alive forever and paying duplicated maintenance indefinitely
Related concepts
Related examples
Authoritative source
Deprecation is a lifecycle signal
Deprecation marks a contract as scheduled for retirement; it does not remove it. The interface keeps working while consumers migrate, and removal happens only after the announced date and a final traffic check. This separates deprecation from deletion, and from versioning, which creates a parallel contract instead of ending one.
How it works
Publish machine-readable signals on every response. RFC 9745 defines Deprecation: @1788307200 as a structured Unix timestamp, while RFC 8594 adds Sunset: Wed, 02 Sep 2026 00:00:00 GMT for the actual removal date. A Link header pointing to the migration guide makes the replacement discoverable from the response itself.
Then instrument the old route by consumer, not just in aggregate. Dashboards should answer which API keys, OAuth clients, or SDK versions still call it. Registered integration owners get direct notices, and short scheduled brownouts surface hidden callers while rollback is still cheap.
When to use it
Deprecate when a field, endpoint, auth mechanism, or entire version must disappear: incompatible semantics, an unsafe protocol, or a maintenance burden that no longer pays for itself. Additive changes that old clients ignore rarely justify deprecation; they usually belong in normal version evolution.
Trade-offs
A long window reduces breakage but extends dual maintenance, duplicated tests, and documentation. Short windows cut cost but shift risk onto consumers who deploy quarterly. Headers help machine clients yet are invisible to humans and may be stripped by proxies, so they complement rather than replace outreach.
Example and misconceptions
A team announces v1 retirement in a changelog but never instruments usage. On the sunset date, 12 percent of production traffic still arrives, and the removal becomes an outage. A safer sequence is header, dashboard, direct notice, brownout, then a 410 response that links to the migration guide.
The common misconception is that a deprecation date is a promise to remove. It is a promise to stop supporting, which still requires a final review of live traffic.
Related concepts: API Versioning, Backward Compatibility, and Semantic Versioning.