Skip to content
releo

Guide

How to deprecate an API

Deprecating an API means announcing that an endpoint, field or version will stop working, then retiring it on a published date. Done well, almost nobody notices. Done badly, it becomes a wave of incidents and support tickets. The difference is mostly process.
By the Releo team · Updated · 7 min read

Deprecation vs sunset

Deprecated means "still works, but do not build on it, and plan to move." Sunset means "stops working on this date." A deprecation without a sunset date is a suggestion; a sunset without prior deprecation is an outage.

The Deprecation and Sunset headers

Two standard HTTP response headers let machines, not just humans, see that a resource is going away:

  • Deprecation (RFC 9745) says the resource is or will be deprecated. Its value is a date expressed as a Unix timestamp prefixed with @.
  • Sunset (RFC 8594) gives the HTTP date after which the resource is expected to become unresponsive.
  • A Link header with rel="deprecation" or rel="sunset" points clients at the documentation that explains what to do.
HTTP/1.1 200 OK
Deprecation: @1767225600
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://api.example.com/docs/migrate-v3>; rel="deprecation"; type="text/html"

Emit these from your gateway where possible, so dates can change without redeploying services. Client SDKs and monitoring can then warn developers automatically.

A deprecation timeline that works

  1. Measure first. Know which clients and accounts call the thing you are retiring, and how often.
  2. Announce in the changelog, by email to affected accounts, and with Deprecation headers. Publish the sunset date and a migration guide at the same time.
  3. Give real notice. Months, not weeks, for anything widely used; longer for core endpoints.
  4. Track migration per account and contact the stragglers directly.
  5. Run brownouts. Short, scheduled windows where the old behavior returns errors surface forgotten callers before the real cutoff.
  6. Sunset. Return 410 Gone with a body that links to the migration guide, rather than a confusing 404.

Write the migration guide your consumers need

A good guide maps every old operation to its replacement, lists behavioral changes explicitly (units, defaults, ordering, error codes), and includes before-and-after code for the most common languages and SDKs.

The hard truth is that even an excellent guide leaves each consumer to find and fix their own call sites, then hope nothing else changed. That work is where most of the cost of a deprecation lands. Providers that hand customers verified pull requests instead of instructions retire versions faster and field fewer tickets. That is the workflow Releo automates.

Frequently asked questions

What is the Sunset HTTP header?

Defined in RFC 8594, the Sunset response header carries an HTTP date after which a resource is expected to become unresponsive. It lets clients and tooling detect upcoming removals automatically.

What is the Deprecation HTTP header?

Defined in RFC 9745, the Deprecation response header signals that a resource is or will be deprecated, using a date written as an @-prefixed Unix timestamp. It is often paired with Sunset and a Link header pointing to migration documentation.

What status code should a sunset API return?

410 Gone is the clearest choice: it tells clients the resource existed and was intentionally removed. Include a body that links to the migration guide.

Coming soon

Ship API changes without breaking your customers.

Releo is in private beta. Join the waitlist for early access.