Deprecation tells a client that the endpoint it just called is deprecated — it still works, but should no longer be used. Sunset gives the date after which it may stop responding. Together with a Link header pointing at the replacement, they let an API announce a retirement inside the traffic itself, where client code can notice it.
Clients and gateways can log or alert when either header appears, so a team learns it depends on a retiring endpoint while there is still time. Sunset holds an HTTP date. A Link header with rel="successor-version" or rel="deprecation" points to the replacement or to migration documentation.
That deprecation notices in a changelog are enough. Nobody reads the changelog of every API they call; headers on the responses reach the code that is actually affected, and a test asserting their absence will fail the day they appear.
GET /friends/v1/characters answers with Deprecation, Sunset and a Link header pointing at the v2 endpoint; assert on them in the Expectations editor with headers.deprecation exists.
All glossary terms · Testing techniques · All 39 mock REST APIs
Last updated