# Deprecation and Sunset Headers — API Design and Versioning

Source: https://www.geekswithgeeks.com/en/api-design/dep-signals

> Signal deprecation in responses so clients and tools can detect it automatically.

## 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.

![Three steps: announce, signal, retire.](assets/figures/api-design/section-6-map.svg) — Figure 6.1 — Announce, signal and retire.

## 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.

```python
# 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.

```python
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
```

**Quiz:** Which header gives the date after which a resource may stop working?

- [ ] ETag
- [x] Sunset
- [ ] Vary
- [ ] Location

*Answer:* Sunset. Sunset (RFC 8594) announces the retirement date; Deprecation marks the resource as deprecated.