Deprecation and Sunset Headers

Tell people in the response itself

Emails get missed, so also signal deprecation in every response from the old version. The Deprecation response header says the resource is deprecated (standardised in RFC 9745), the Sunset header (RFC 8594) gives the HTTP-date after which it may stop working, and a Link header with rel="successor-version" points to the replacement (and rel="deprecation" can point to documentation). Clients can log or alert when they see these, and API gateways can aggregate who is still calling deprecated endpoints. Also update docs, the changelog and the OpenAPI spec (deprecated: true).

Retire old versions with respect

A clear timeline, machine-readable signals and good tooling let clients move on without panic.

Headers on the deprecated v1, run

I ran this against a small real HTTP API built with only the Python standard library (full code in the case study). The v1 response carries Deprecation: true, Sunset: Wed, 31 Dec 2026 23:59:59 GMT and a Link header pointing to /v2/items/1 as the successor.

# uses srv, base and call() from the runnable demo in the case study
s, h, b = call("GET", "/v1/items/1"); print(s, b, h.get("Deprecation"), h.get("Sunset")); print(h.get("Link"))
s, h, b = call("GET", "/v2/items/1"); print(s, b, h.get("Deprecation"))

Output:

200 {'id': 1, 'name': 'Asha Rao', 'plan': 'pro'} true Wed, 31 Dec 2026 23:59:59 GMT
</v2/items/1>; rel="successor-version"
200 {'id': 1, 'first_name': 'Asha', 'last_name': 'Rao', 'plan': 'pro'} None

Time left until sunset, run

I ran this plain-Python example. From 1 October 2026 to the 31 December 2026 sunset there are 91 days. Use a calculation like this to schedule reminders and decide when to start blocking new integrations.

import hmac, hashlib, json, time, bisect

from datetime import datetime, timezone
sunset = datetime(2026, 12, 31, 23, 59, 59, tzinfo=timezone.utc); today = datetime(2026, 10, 1, tzinfo=timezone.utc)
print((sunset - today).days, "days left")

Output:

91 days left

Quick check: Which header gives the date after which a resource may stop working?

• ETag
• Sunset
• Vary
• Location