API Deprecation

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
}

References

• ↗ https://datatracker.ietf.org/doc/html/rfc8594

Tags

Related Terms