API Deprecation
debt(d7/e5/b5/t7)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints indicate automated detection is 'no'. While OpenAPI specs and Datadog can help identify deprecated endpoints lacking Sunset headers, there's no automated enforcement that catches missing deprecation workflows at development time. The real failures — removing endpoints without notice, not tracking usage — are only discovered through careful review of API lifecycle practices or when production consumers break. Bumped slightly from d9 because tools like OpenAPI linting can flag missing deprecation metadata if configured.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix suggests adding Deprecation and Sunset headers, which sounds like a small change, but proper deprecation is more than headers — it requires setting up usage monitoring/logging per deprecated endpoint, publishing migration guides, coordinating with consumers, and managing the lifecycle across potentially many endpoints. This touches middleware, logging infrastructure, documentation, and monitoring dashboards. Not quite cross-cutting (e7) since it's contained within the API layer, but definitely more than a simple parameterised fix.
Closest to 'persistent productivity tax' (b5). API deprecation applies to web/api contexts and is an ongoing process concern. Every API change that removes or modifies behavior must go through the deprecation lifecycle. This creates a persistent tax on teams: maintaining deprecated endpoints alongside new ones, monitoring usage, managing sunset timelines, and supporting consumers during migration windows. It shapes how teams plan releases but doesn't define the entire system architecture, so b7 would be too high.
Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception is highly revealing: developers believe removing an undocumented endpoint isn't a breaking change. This contradicts the intuitive mental model that 'undocumented = unsupported = safe to remove.' Hyrum's Law makes this a serious trap because the 'obvious' approach (just remove it, nobody should be using it) is wrong. Additionally, many developers coming from internal-only APIs or library deprecation (where you control all callers) will underestimate the impact on external consumers they can't see or coordinate with.
Also Known As
TL;DR
Explanation
API deprecation follows a lifecycle: announce, deprecate (still works, signals removal), sunset (stop accepting new integrations), remove. The Sunset HTTP header (RFC 8594) carries the removal date. Deprecation-Warning response headers flag deprecated endpoints. Semver breaking changes require a major version bump. In practice: give consumers at least 6-12 months notice, provide a migration guide, log deprecated endpoint usage to identify who still uses them before removal.
Diagram
flowchart LR
V1[v1 endpoint active] -->|add v2| BOTH[v1 and v2 both active]
BOTH -->|announce sunset| DEP[v1 deprecated<br/>Deprecation header added<br/>Sunset: date header]
DEP -->|sunset date reached| GONE[v1 removed<br/>410 Gone response]
subgraph Communication
DOCS[Update API docs]
EMAIL[Email API consumers]
HEADER[Deprecation: true<br/>Link: migration guide]
MONITOR[Monitor v1 traffic<br/>contact active users]
end
BOTH --> DOCS & EMAIL & HEADER & MONITOR
style V1 fill:#d29922,color:#fff
style GONE fill:#f85149,color:#fff
style BOTH fill:#238636,color:#fff
Common Misconception
Why It Matters
Common Mistakes
- Removing endpoints without a deprecation period — production integrations break with no warning.
- Not including the Sunset date in the response header — consumers only discover the removal after it happens.
- Too short a deprecation window — 2-week windows are insufficient for enterprise consumers with change management processes.
- Not monitoring who uses deprecated endpoints — removes while active consumers exist.
Avoid When
- Deprecating without a migration path — consumers cannot act on a deprecation notice with no alternative.
- Deprecating with too short a sunset window — external consumers need months, not days, to migrate.
- Removing deprecated endpoints without checking actual usage — monitor traffic before hard removal.
When To Use
- Before any breaking change — deprecate the old behaviour, ship the new, give consumers time to migrate.
- Communicating via Deprecation and Sunset HTTP headers so automated tooling can detect and alert.
- Publishing a changelog and migration guide alongside the deprecation notice.
- Setting a concrete sunset date — open-ended deprecations are ignored; deadlines create urgency.
Code Examples
// No deprecation notice — silent breaking change:
// Sprint 42: remove GET /api/v1/users/:id/preferences
// Deploy to production
// Consumer monitoring alerts fire — integration broken with no warning// Deprecation with Sunset header:
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://api.example.com/docs/migration/preferences>; rel="successor-version"
// Log deprecated endpoint usage:
if ($request->is('api/v1/users/*/preferences')) {
$this->deprecationLog->record($request->route(), $apiKey);
// Alert team when consumer count drops to 0 — safe to remove
}