Handling Deprecation
1. Announcing Deprecation
| Lead Time | Audience |
|---|---|
| 3-6 months minimum | Public APIs |
| 6-12 months | Enterprise customers |
| 2+ years | Major platform shifts |
2. Using Deprecation Header
| Header | RFC |
|---|---|
Deprecation: true | RFC 9745 — boolean flag |
Deprecation: @1735689600 | Unix timestamp deprecated since |
3. Using Sunset Header
Example: Deprecation + Sunset
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"
Link: <https://docs.example.com/v1-to-v2>; rel="deprecation"4. Providing Migration Guides
| Section | Content |
|---|---|
| What's changing | List of removed/renamed/changed elements |
| Why | Rationale (performance, security) |
| Step-by-step | Code before/after |
| Tooling | Codemods, automated migration scripts |
| Timeline | Deprecation date, sunset date |
5. Maintaining Deprecated Endpoints
| During Sunset Window | Maintenance Level |
|---|---|
| Security patches | Always |
| Critical bugs | Yes |
| New features | No |
| Performance work | Minimal |
6. Returning Warning Headers
| Header | Format |
|---|---|
Warning: 299 - "Deprecated API" | Generic warning |
Warning: 299 example.com "Field 'foo' deprecated; use 'bar'" | With agent |
| Note | Warning header is itself deprecated in HTTP semantics; use Deprecation/Sunset |
7. Documenting Deprecation Timeline
| Milestone | Date |
|---|---|
| Announced | 2026-05-15 |
| Deprecation header live | 2026-06-01 |
| Final warning email | 2026-12-01 |
| Sunset (removed) | 2027-01-01 |
8. Implementing Feature Flags
| Use | Benefit |
|---|---|
| Gradual rollback | Re-enable deprecated path if regressions found |
| Per-customer override | Extend lifeline for key accounts |
| Dark launch new version | Test before public flip |
9. Notifying API Consumers
| Channel | When |
|---|---|
| Initial + 30-day reminder + 7-day final | |
| Dashboard banner | Continuous |
| Response headers | Every request after deprecation |
| Webhooks/Slack | Status feed for power users |
10. Removing Deprecated Endpoints
| Sunset Day Behavior | Status |
|---|---|
| Hard removal | 410 Gone |
| Redirect to new | 301/308 (only if compatible) |
| Grace period | 410 + extended notice for late adopters |