api-deprecation

Safe API deprecation requires a five-stage lifecycle: announce timelines, mark endpoints with Sunset and Deprecation HTTP headers, instrument per-consumer telemetry, provide a migration path, and execute removal with 410 Gone brownout mechanics and a recovery playbook for holdouts.

API deprecation signaling uses RFC 8594 Sunset headers and Deprecation headers so client applications can programmatically detect that an endpoint, field, or behavior is being phased out and plan migration accordingly.

Handle unmigrated consumers by executing 410 Gone brownout mechanics, extending allow-lists for critical holdouts, and following a structured recovery playbook that includes escalation procedures and post-mortems to manage final removal.

An API deprecation lifecycle is needed for schema changes when consumers still rely on older surfaces, such as removing schema fields, migrating authentication schemes, or updating webhook payloads, ensuring a structured and measurable migration path.

Plan a v1 to v2 API sunset by specifying what endpoints to retire, who is affected, the announce-to-sunset window, the migration supports provided, and the telemetry and brownout mechanics used to enforce the transition safely.