Sunset Your API Endpoints on Purpose: The Deprecation and Sunset Headers

#tutorial #webdev #api #http

Killing an API endpoint is easy. Killing it without breaking your consumers is the hard part. Most teams announce a deprecation in a blog post, send one email, and then act surprised when integrations break six months later. The clients that broke never read the blog post — but their code reads your HTTP responses on every single request. That's where the deprecation notice belongs.

Two standardized headers let you signal the full lifecycle of an endpoint directly in the response: Deprecation and Sunset. Used together, they turn a silent breaking change into a loud, machine-readable countdown.

The two headers

The Sunset header (RFC 8594) tells clients the date and time after which the resource is expected to stop working. The Deprecation header (an IETF draft, but widely adopted) tells clients that the resource is deprecated now — optionally with the date it became deprecated.

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: Sun, 01 Nov 2026 00:00:00 GMT
Sunset: Wed, 01 Apr 2027 00:00:00 GMT
Link: <https://api.example.com/docs/migrating-to-v2>; rel="deprecation"; type="text/html"

The Link header with rel="deprecation" points to human-readable migration docs. Together these say: this endpoint was deprecated on Nov 1, it will be removed on Apr 1, and here's how to migrate.

Adding it on the server

You don't need a framework feature — it's just response headers. Here's a small Express middleware you can attach to any route group you're retiring:

function deprecate({ deprecatedOn, sunsetOn, docs }) {
  const dep = new Date(deprecatedOn).toUTCString();
  const sun = new Date(sunsetOn).toUTCString();
  return (req, res, next) => {
    res.set("Deprecation", dep);
    res.set("Sunset", sun);
    res.set("Link", `<${docs}>; rel="deprecation"; type="text/html"`);
    next();
  };
}

app.use(
  "/v1/orders",
  deprecate({
    deprecatedOn: "2026-11-01",
    sunsetOn: "2027-04-01",
    docs: "https://api.example.com/docs/migrating-to-v2",
  })
);

In FastAPI it's just as small:

from fastapi import APIRouter, Response

router = APIRouter()

@router.get("/v1/orders")
def list_orders(response: Response):
    response.headers["Deprecation"] = "Sun, 01 Nov 2026 00:00:00 GMT"
    response.headers["Sunset"] = "Wed, 01 Apr 2027 00:00:00 GMT"
    response.headers["Link"] = (
        '<https://api.example.com/docs/migrating-to-v2>; '
        'rel="deprecation"; type="text/html"'
    )
    return {"orders": []}

Reading it on the client

The whole point is that consumers can detect the countdown automatically. A thin wrapper around fetch can warn the moment a deprecated endpoint is touched:

async function apiFetch(url, options) {
  const res = await fetch(url, options);
  const sunset = res.headers.get("Sunset");
  if (res.headers.get("Deprecation") || sunset) {
    const when = sunset ? ` Removal: ${sunset}.` : "";
    console.warn(`[deprecated] ${url} is deprecated.${when}`);
  }
  return res;
}

Pipe that warning into your logging or alerting stack and a deprecation stops being something a human has to remember — your CI logs start nagging you the day the header appears.

Doing it right

A few rules make the difference between a smooth retirement and an angry support queue. Set the Sunset date far enough out to be realistic — months, not weeks — and never move it closer once published. Keep returning real data until the sunset date; the headers are a warning, not a 410 Gone. Always include the Link to migration docs, because a date with no instructions just creates panic. And monitor traffic to the deprecated endpoint so you know whether anyone is actually still calling it before you pull the plug.

Closing

Deprecation headers are a small addition with an outsized payoff: every response becomes self-documenting about its own expiry, and your consumers get a programmatic heads-up instead of a nasty surprise. The hard part is staying consistent — applying the headers everywhere, keeping the dates accurate, and verifying clients actually see them. That's the kind of cross-cutting API concern a tool like APIKumo is built for: you can inspect response headers across every endpoint, script checks that assert your Deprecation and Sunset values are present and correct, and document the migration path right alongside the live API. Sunset your endpoints on purpose — not by accident.

DEV Community