Deprecation and Sunset — API Platform & Lifecycle

Deprecation is a process: announce (changelog, docs, emails), signal in-band with the Deprecation header (RFC 9745) and Sunset header (RFC 8594) plus a Link to the migration guide, measure remaining usage per consumer, contact laggards, optionally run brownouts (scheduled short outages of the old endpoint) to surface forgotten integrations, and remove after the sunset date. Keep returning 410 Gone with a helpful message for a while after removal.

Deprecation timeline

Phase	Actions
Announce	Changelog, docs banner, email affected consumers, SDK warnings
Signal	Deprecation + Sunset + Link headers on responses
Measure	Usage per consumer; reminders
Brownouts	Short scheduled failures to flush out forgotten callers
Remove	410 Gone with migration info; monitor errors

HTTP/1.1 200 OK
Deprecation: @1767225600
Sunset: Wed, 30 Jun 2027 00:00:00 GMT
Link: <https://developer.example.com/migrate/v2-orders>; rel="deprecation"; type="text/html"

# After removal
HTTP/1.1 410 Gone
Content-Type: application/problem+json
{"type": "https://api.example.com/problems/endpoint-retired", "title": "This endpoint was retired on 2027-06-30",
 "detail": "Use GET /v2/orders. Migration guide: https://developer.example.com/migrate/v2-orders"}

Common pitfalls

Deprecating without usage data.
Sunset dates that silently slip forever.
Removing without a 410 and explanation.

Key points

Deprecation (RFC 9745) + Sunset (RFC 8594) headers
Usage-driven outreach; brownouts
410 Gone after removal

Further reading: RFC 9745: The Deprecation HTTP Response Header Field

Practice questions

What's the difference between the Deprecation and Sunset headers?

Answer

Deprecation signals that the resource is (or will be) deprecated and since when; Sunset gives the date after which it will stop being available.

What is an API brownout?

Answer

Deliberately making a deprecated endpoint fail for short, announced windows before removal so forgotten integrations surface while there's still time to migrate.