Skip to content

We use analytics cookies to see how the site is used. They are only set if you accept. Accepting also turns on session recording (pages viewed, clicks and scrolls) so we can fix problems; what you type stays hidden. It also lets Meta (Facebook) see your visit, so we can measure our ads. Read the privacy policy

A gold sun half sunk behind a horizon above two lines showing the Deprecation and Sunset response headers.

The API Owner's AlmanacNovember 20267 min read

API Deprecation: The Sunset Header, Notice Periods and a Calendar for Retiring a Version

Retiring an API takes two dates. How the Deprecation and Sunset headers carry them, how much notice GitHub, Microsoft, Shopify and Anthropic give, and a 12-month calendar.

Deprecation
Stop recommending
Sunset
Stop answering

Leaf 1 of 6

The short answer

Retiring an endpoint takes two dates, not one: the day you stop recommending it and the day it stops answering. Publish both in your docs, send both on every response, and leave a long gap between them.

RFC 9745 says the first date changes nothing about behavior: consumers can keep using the resource as before. RFC 8594 covers the second: the moment a URI is expected to become unresponsive.

Leaf 2 of 6

The two headers, side by side

This response says the version is deprecated from 1 December 2026, goes away on 1 December 2027, and where to read more:

HTTP/1.1 200 OK
Deprecation: @1796083200
Sunset: Wed, 01 Dec 2027 00:00:00 GMT
Link: <https://example.com/docs/v1-retirement>; rel="deprecation"; type="text/html"
DeprecationSunset
Defined inRFC 9745, Standards Track, 2025RFC 8594, Informational, 2019
Date formatStructured field date: @ plus Unix secondsHTTP date
MeaningWill be or has been deprecatedExpected to become unresponsive
Date in the pastNormal: it was deprecated thenTreat it as now: it can go at any time
Behavior changesNoneAfter the date, expect 4xx, 3xx or no answer

Three rules catch people out. The formats differ on purpose: RFC 9745 calls it history. The Sunset date must not be earlier than the Deprecation date. And both are hints, so a client must still work if they never appear.

Formats differ in the wild too. GitHub's docs describe their Deprecation value as an HTTP date, not the @ form, so a client that parses the header should accept both.

Leaf 3 of 6

How much notice the big APIs give

No RFC sets a notice period. These are the published promises, read on 1 November 2026:

ProviderPromiseAfter the end
GitHub REST24 months after a newer version ships410 Gone
Microsoft GraphDeprecated at least 24 months before retiringVersion or API retired
ShopifyEach stable version at least 12 months, at least 9 months of overlapFalls forward to the oldest accessible version
Anthropic modelsAt least 60 days for publicly released modelsRequests fail
StripeSaid in 2017 it had kept every version since 2011Pinned versions kept working

The spread follows the cost of moving. A model swap can be one string, while a payment or commerce integration may touch code nobody has opened in years. Set your number by how hard your slowest paying customer finds the move, then publish it.

Security is the usual exception: GitHub reserves the right to act without advance notice, and Microsoft exempts service security and reliability issues.

Leaf 4 of 6

Decide what the last day does

The real choice is what a late request gets. Each option breaks differently:

Fail loudly

GitHub returns 410 Gone. The break is obvious and easy to diagnose, and it is an outage for anyone who ignored the notice. Put a link to the migration guide in the error body.

Fall forward

Shopify answers from the oldest accessible stable version. Nothing goes down, but the shape of the response may change under code that never asked for it.

Watch unversioned callers either way. GitHub says requests with no version header default to the next oldest supported version, so behavior can shift for them as old versions leave. Ask for a pinned version from the first day of your API.

Leaf 5 of 6

A 12-month calendar for a small API

This is our suggested plan, not a standard. Shorten it if every caller is a team you can reach directly.

  1. Before day 0

    Count the callers

    Log the version per API key. You cannot warn people you cannot name, and the list tells you who needs a personal email.

  2. Month 0

    Announce and start the headers

    Ship the replacement and the migration guide first. Then publish both dates in the changelog and turn on Deprecation, Sunset and the Link header.

  3. Month 1

    Close the door to new users

    Stop issuing the old version to new keys. Microsoft describes the same step: new applications may have to start on the new API soon after deprecation.

  4. Months 3 to 9

    Email the callers still on it

    Send only to keys seen on the old version, and name the endpoints each one used. A generic blast is easy to ignore.

  5. Month 11

    Run short brownouts

    Turn the old version off for a few announced minutes, in working hours. Forgotten cron jobs fail while their owners still have time to fix them.

  6. Month 12

    Sunset, and keep the door sign up

    Return 410 Gone with a link to the guide, and keep that answer running. Check the log first: if a paying customer is still there, call them.

Leaf 6 of 6

On the client side, and common questions

RFC 8594 warns that clients that ignore the header simply see the resource vanish. Your own integrations can do better with a few lines:

const sunset = res.headers.get('sunset')
if (sunset) {
  logger.warn('API sunset announced', { url: res.url, sunset })
}
Should I send a Sunset header on the replacement too?

No. Send it only on what is going away, or clients learn to ignore it.

Can a single header cover a whole API?

By default each header applies to the resource that returned it. Both RFCs allow a wider scope if you document it, though clients that have not read your docs will not know.

Is OpenAPI's deprecated flag enough?

It helps people reading the docs. Running code never sees it, so keep the headers too.

Sources