Every deprecated API operation must announce itself in-band using Deprecation and Sunset headers that tell consumers a change is coming and when it lands. I require that deprecation be signaled through the response itself, not only in a changelog a consumer may never read. Machine-readable sunset dates let clients and agents plan migrations before an endpoint disappears, which is the difference between an orderly transition and a broken integration. I treat clear deprecation signaling as a baseline courtesy and a governance requirement for any API that changes over time.
Deprecation Sunset Headers
Rules
OpenAPI Operation Deprecated Sunset Info
A deprecated operation should provide a Sunset response header so consumers know when the operation will be removed and can plan their migration. Pairing deprecation with a Sunset header makes the ...
Experiences
Change
Managing and effectively communicating changes across one or more APIs is a leading cause of instability and friction in enterprise operations. While these changes often surface in applications use...
Stability
Stability is the experience of being able to depend on an API not breaking underneath you. It is built on thoughtful versioning, backward compatibility, clear change communication, and honoring com...
Lifecycle
event_busy Deprecation Deprecate
Every API ends, and deprecation is how you end one with dignity. Clear timelines, communication, and sunset headers give consumers the runway they need to move on. How I deprecate an API tells cons...
