api-deprecation-rolloutlisted

# API Deprecation Rollout ## When to Use This Skill When a breaking change requires retiring an existing API version (major bump), or when removing an individual operation/field that consumers depend on. ## 1. Deprecation vs. Sunset | Term | Meaning | Header | |---|---|---| | **Deprecated** | Still works; consumers should migrate | `Deprecation: @<unix-ts>` (RFC 9745) | | **Sunset** | Will stop working on this date | `Sunset: <date>` | | **Retired** | Endpoint returns `410 Gone` | No header needed | `Sunset` uses the RFC 7231 HTTP-date format (`Sunset: Sat, 01 Aug 2025 00:00:00 GMT`); `Deprecation` (RFC 9745) uses a Structured-Fields Date — an `@` followed by a Unix timestamp in seconds (`Deprecation: @1738368000`). ## 2. Rollout Timeline Template | Phase | Duration | Action | |---|---|---| | **Announce** | Day 0 | Publish deprecation notice; add headers to all responses on old version; update developer portal; email registered consumers | | **Migration window** | 90 days min (180 for high-traffic APIs) | Monitor old-version traffic; publish migration guide; offer upgrade office hours | | **Sunset warning** | 30 days before retirement | Increase warning cadence; add `Link: <sunset-date>; rel="sunset"` header; block new app registrations on old version | | **Sunset** | Day N | Return `410 Gone` with a Problem Details body pointing to the new version | | **Remove** | 30 days after sunset | Remove code, teardown infra, archive spec | ## 3. Required Headers on Every Respo