API deprecation is the act of telling the developers who use your API that a version, an endpoint, or a field is no longer recommended and is scheduled to go away. The deprecated thing keeps working — deprecation is a warning with a date on it, and the removal (the sunset) comes later. Done well, it’s a boring, predictable process that nobody remembers. Done badly, it’s an outage in somebody else’s production system with your name on it.
Here’s the short version of how to deprecate an API properly: write a deprecation policy before you need one, announce every deprecation with a sunset date and a migration path, send the Deprecation and Sunset headers on every affected response, measure who’s still calling the old surface, and only turn it off once the notice window you promised has passed.
The rest of this guide fills in each step, with the current published practice from GitHub, Stripe, Shopify, Kubernetes, and Slack — and a deprecation notice you can copy.
Jump to: Deprecated vs sunset · What counts as breaking · A deprecation policy · Deprecation and Sunset headers · Notice windows · Writing the notice · Rollout · Checklist
What API deprecation means: deprecated vs sunset vs retired
The words get used loosely, so it’s worth pinning them down. The two IETF documents that cover this area draw the line clearly. RFC 8594 describes deprecation as happening “in two stages”: first the API “is not the preferred or recommended version anymore,” and then it “gets decommissioned.” RFC 9745 is blunter about the first stage: “The act of deprecation does not change any behavior of the resource.”
| Stage | What it means | What a caller sees |
|---|---|---|
| Active | Recommended and supported | Normal responses |
| Deprecated | Still works, no longer recommended, removal date announced | Normal responses, plus deprecation signals |
| Sunset / retired | Switched off | An error — typically 410 Gone or 404 Not Found |
“Sunset,” “retired,” “end of life,” and “decommissioned” all describe that last row. GitHub’s docs use “closing down” for the deprecated stage. Whatever vocabulary you pick, pick one and use it consistently — a changelog that says “deprecated” when it means “removed today” teaches developers to ignore the word.
Deprecation also applies at different sizes: a whole API, one version of it, a single endpoint, or one field or parameter in a response. The process is the same at every size, and the smaller the unit, the more often you’ll run it.
What counts as a breaking change
You only need a deprecation cycle for changes that can break a working integration, so the first thing a policy has to settle is which changes those are. You don’t have to invent the list, because the big API providers publish theirs.
GitHub’s REST API docs define breaking changes as “changes that can potentially break an integration” and enumerate them:
| Breaking (needs a new version and notice) | Additive (ships to all supported versions) |
|---|---|
| Removing an entire operation | Adding an operation |
| Removing or renaming a parameter | Adding an optional parameter |
| Removing or renaming a response field | Adding an optional request header |
| Adding a new required parameter | Adding a response field |
| Making an optional parameter required | Adding a response header |
| Changing the type of a parameter or response field | Adding enum values |
| Removing enum values | |
| Adding a new validation rule to an existing parameter | |
| Changing authentication or authorization requirements |
Stripe’s versioning docs publish the same idea from the other side — the changes Stripe considers backward-compatible: adding new API resources, adding optional request parameters, adding properties to existing responses, changing the order of properties in responses, changing the length or format of opaque strings such as object IDs, and adding new event types.
Google’s AIP-180 covers the cases a field-by-field list misses. Compatibility isn’t only about the wire format, it’s about behavior: “APIs must not change visible behavior or semantics in ways that are likely to break reasonable user code,” and that holds even for behavior you never documented. Default values mustn’t change. A field’s type mustn’t change even when the new type is wire-compatible. Its example is worth remembering — adding pagination to an endpoint that used to return everything looks additive, but an old client will quietly assume the first page is the full result.
Notice the grey area too: GitHub treats a new enum value as additive, while AIP-180 warns that “user code does not handle new values gracefully” and asks for caution. That’s exactly the kind of call your own policy should make in writing, once, instead of in a hurry on release day.
An API deprecation policy you can adopt
A deprecation policy is a short public page that answers six questions. Here’s a starting point you can paste into your docs and edit — the numbers are placeholders to adjust for your product, and what matters most is that the page exists before your first deprecation does.
# API deprecation policy
**What counts as breaking.** Removing or renaming an endpoint, parameter,
or response field; adding a required parameter; changing a type, default,
or validation rule; removing an enum value; changing authentication.
Everything additive ships without notice, so clients must ignore fields
and enum values they don't recognise.
**Notice period.** Stable (GA) endpoints and fields keep working for at
least 12 months after their deprecation is announced. Beta surfaces get
at least 90 days. Anything marked experimental can change without notice.
**How we announce it.** Every deprecation is posted in the API changelog
on the day it is decided, with the sunset date and a migration guide.
Account owners with recent traffic to the affected surface are emailed
at announcement, 90 days out, and 30 days out.
**Signals in the API.** Deprecated resources return `Deprecation` and
`Sunset` response headers and are marked `deprecated: true` in the
OpenAPI description.
**After the sunset date.** Requests return `410 Gone` with a link to the
migration guide.
**Exceptions.** We may act faster to fix a security vulnerability or meet
a legal requirement, and we'll explain what changed and why.
None of that is exotic, and each clause mirrors a policy that’s public today:
- Kubernetes ties the window to stability level. GA API versions “may be marked as deprecated, but must not be removed within a major version,” beta versions keep being served for “9 months or 3 minor releases after deprecation (whichever is longer),” and alpha versions “may be removed in any release without prior deprecation notice.” (If the alpha, beta, and GA labels themselves need untangling, that’s what the release candidate guide is for.)
- IBM Security Verify commits to notice “at least 12 months before the proposed end of life date,” marks deprecated APIs with the
deprecatedtag in its Swagger definitions, and returns aSunsetresponse header on them. - GitHub keeps a carve-out for emergencies: security, availability, and reliability issues can force a change outside the normal schedule, communicated through release notes, changelogs, and direct contact.
- Shopify spells out the channels — the developer changelog, alerts in the app’s dashboard, the API reference, and for imminent breaking changes, the app’s emergency developer contact.
One design decision sits underneath the policy: how consumers pick which version of your API they’re talking to. GitHub and Shopify use date-named versions (2026-03-10, 2026-10), and Stripe uses dated versions inside named major releases (2026-10-28.endive), where only the twice-a-year major releases contain breaking changes and the monthly ones don’t. Date-based names have a useful side effect for deprecation — the version string tells a developer how old their integration is. Numbered versions follow different rules, and the semantic versioning guide covers those.
The Deprecation and Sunset headers
A changelog post only reaches developers who read your changelog. The two deprecation headers put the warning inside the API response, where logs, gateways, SDKs, and monitoring can pick it up without a human in the loop.
The Deprecation header — RFC 9745. Published in March 2025 as a Standards Track RFC, it signals that a resource “will be or has been deprecated.” Its value is a date in the HTTP structured-fields format: an @ followed by Unix seconds. The date can be in the past (already deprecated) or in the future (will be deprecated then).
The Sunset header — RFC 8594. Published in May 2019 as an Informational RFC, it “indicates that a URI is likely to become unresponsive at a specified point in the future.” Its value is an ordinary HTTP-date, the same format as Last-Modified. RFC 9745 notes the two headers use different date formats “for historical reasons,” and requires that the sunset timestamp is never earlier than the deprecation one.
Both RFCs also register a link relation — deprecation and sunset — so you can point at the human-readable docs from a Link header. A response from an endpoint deprecated on December 1, 2026 and scheduled for removal a year later looks like this:
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1796083200
Sunset: Wed, 01 Dec 2027 00:00:00 GMT
Link: <https://developer.example.com/deprecations/customer-email>; rel="deprecation"; type="text/html"
A few details that are easy to get wrong:
Sunseton its own doesn’t mean “deprecated.” RFC 8594 was written for any resource with a known end date — a pending order that expires, a record under a retention rule. Send both headers for a deprecation.- Both are hints. Each RFC says clients should treat the dates as hints, and a client should keep working if it never reads them. They add to your announcement and don’t replace it.
- Scope is per-resource by default. The header describes the URL that returned it. If you want one header on your API’s root to mean “this whole version is going away,” RFC 9745 allows that, but only clients who’ve read your docs will know.
- Check the format of the API you consume. GitHub sends both headers as a REST API version approaches the end of its support window, and its docs describe the
Deprecationvalue as an HTTP-date (Wed, 27 Nov 2019 14:34:29 GMT), not the@-timestamp RFC 9745 settled on. A client that parses these should accept both.
Two other machine-readable signals are worth the five minutes they take. The OpenAPI Specification has a boolean deprecated field on operations and parameters — “Consumers SHOULD refrain from usage of the declared operation” — which documentation generators can surface in the rendered reference. And Kubernetes has returned a Warning header on requests to deprecated API endpoints since v1.19, which is a reasonable pattern if you want the message itself, not only a date, in the response.
How much notice? What the big APIs actually give
These are the published numbers as of November 2026, each from the provider’s own documentation:
| Provider | Published window | Detail |
|---|---|---|
| GitHub REST API | At least 24 months per version | Counted from the release of the next version. Version 2022-11-28 ends support on March 10, 2028 — 24 months after 2026-03-10 shipped |
| Shopify | At least 12 months per version | A new version every three months, with at least nine months of overlap between consecutive versions |
| Kubernetes | GA: not removed within a major version. Beta: 9 months or 3 minor releases | Whichever is longer, counted from deprecation |
| IBM Security Verify | 12 months | Notice issued at least 12 months before end of life |
Slack files.upload |
About 11 months, later extended | Announced April 2024 for a March 11, 2025 sunset, then moved to November 12, 2025 |
What happens after the window differs as well, and it’s part of the policy. GitHub returns 410 Gone for a version that’s no longer supported. Shopify does the opposite and “falls forward” — a request for a retired version is answered by the oldest accessible stable one, and the X-Shopify-API-Version response header tells you which version actually served it. Shopify’s enforcement runs through distribution: an app that keeps calling unsupported resources after the deadline is delisted from the Shopify App Store.
If you’re choosing a number for your own API, a year is a defensible default for anything paying customers depend on, and 24 months is what the largest platforms hold themselves to. A smaller API with a few dozen integrations can move faster, especially if you know every integrator by name. What you can’t do is decide the window in the same week you announce the deprecation — a notice period invented under pressure reads as a countdown, while one that’s been sitting in your docs for a year reads as a contract.
How to write an API deprecation notice
The deprecation notice is a changelog entry, and it’s the most consequential kind of API release note you’ll write. A developer should be able to tell within a few seconds whether it applies to them. Structure it to answer five questions, in this order:
- What’s deprecated? Name the exact endpoint, field, or version. “The
customer.emailfield is deprecated in favor ofcustomer.primary_email” — not “we’ve improved our customer model.” - What kind of change is it? A label up front. Keep a Changelog already has the two you need: Deprecated “for soon-to-be removed features” and Removed “for now removed features.” Add Breaking for anything that isn’t additive.
- Who’s affected? “Anyone reading
customer.emailfromGET /v2/customersor thecustomer.updatedwebhook.” - What do they do instead? The replacement, the migration step, and a link to the guide.
- By when? The sunset date as a date. “In the coming months” isn’t a deadline.
Here’s a notice that does all five:
## 2026-12-01 — Deprecated: customer.email
`customer.email` is deprecated and will be removed on **December 1, 2027**.
Use `customer.primary_email` instead, which is available today.
**Affected:** `GET /v2/customers`, `GET /v2/customers/:id`, and all
`customer.*` webhook payloads.
**What to do:** read `primary_email` wherever you read `email`. Both
fields return the same value until the sunset date.
**Timeline**
- 2026-12-01: deprecated. Responses include `Deprecation` and `Sunset` headers.
- 2027-09-01: reminder emails to accounts still reading the field.
- 2027-12-01: `email` is removed from responses and webhook payloads.
Migration guide: https://developer.example.com/migrate/customer-email
What’s missing matters as much as what’s there: no adjectives, no apology, no “we’re excited to.” API notices are the one changelog genre where personality gets in the way, so keep the voice for your product release notes and let precision carry this one.
Two more habits separate a good API changelog from a merely complete one. First, when a date changes, edit the original notice visibly — Slack’s files.upload entry still shows the March 11, 2025 date struck through next to the new November 12, 2025 one, so nobody has to wonder which announcement is current. Second, tag deprecations so they can be filtered. Slack’s developer changelog has dedicated “Deprecation” and “Breaking change” tags, and GitHub keeps a breaking-changes page with a section for each API version. An integrator who can subscribe to only the entries that require action is far more likely to read them.
Rolling it out: channels, measurement, and the last mile
A deprecation is a campaign that runs for the whole notice window, with the same message repeated across channels. This is the order that works:
- Changelog entry, on the day the deprecation is decided. Publish the date even if it’s a year away. This is the canonical record every other channel links to.
- Headers and the OpenAPI
deprecatedflag, from the same day. The machine-readable signals should never lag the announcement. - Docs. A banner on the deprecated endpoint’s reference page and a migration guide that shows before-and-after requests.
- Direct outreach to whoever is still calling it. This is the step that actually moves the usage numbers. Shopify attributes deprecated calls to the app whose access token made them and flags them in that app’s dashboard alerts, which is the model to copy at whatever scale you can manage.
- Reminders. Repeat the changelog entry and the emails as the date approaches. The repetition feels excessive from the inside and it’s barely enough from the outside.
Instrument the other direction too. If you can’t list which accounts called the deprecated surface in the last 30 days, you can’t tell whether your communication worked, and you can’t make an informed decision when someone asks for an extension. Log usage per API key before you announce anything.
Then automate the part people forget — noticing that a change is breaking in the first place. If you maintain an OpenAPI description, oasdiff compares two versions of it: its breaking command reports “only the changes that break existing API clients,” and changelog lists the changes that can affect consumers “in human-readable form.” Run it in CI and a breaking change can’t merge unannounced. If your team writes Conventional Commits, the ! marker and BREAKING CHANGE: footer carry the same flag through your commit history into the release notes.
There’s one more reader to plan for. When an integration breaks, plenty of developers now ask an AI coding assistant why before they open your docs, and those assistants answer from whatever your changelog exposes to them. A dated, labeled deprecation notice at a stable URL gives the assistant something accurate to quote, which beats a guess built from last year’s documentation.
The API deprecation checklist
Before you announce:
- The change is confirmed as breaking against your written definition
- The replacement is live and documented, so there’s something to migrate to
- The sunset date honors the notice period in your deprecation policy
- You can list the accounts currently using the deprecated surface
On announcement day:
- Changelog entry published, labeled Deprecated, with the sunset date and a migration guide link
DeprecationandSunsetheaders on every affected response, plus aLinkheader withrel="deprecation"deprecated: truein the OpenAPI description- Banner on the reference page
- Email to the affected accounts
During the window:
- Reminders at the intervals your policy promises
- Usage tracked, with direct outreach to the remaining callers
- Any date change edited into the original notice, visibly
On sunset day:
- The documented post-sunset response (for example
410 Gone) with a pointer to the migration guide - A final changelog entry, labeled Removed
If you want a starting scaffold for the changelog side, the release notes templates include an API and developer changelog format with Deprecated and Breaking sections already laid out.
Where ReleasePad fits
The policy, the headers, and the usage tracking live in your API and your docs — no changelog tool does those for you. What ReleasePad covers is the announcement channel: a public changelog page with categories you can use for Deprecated and Breaking entries, an RSS feed integrators can subscribe to, and a Markdown version of the same page for AI tools. You can post notices from your release pipeline through the Management API, and a webhook fires when a post is published if you want the same notice pushed into Slack or an email tool. It’s free to start, so it’s an easy way to give deprecations a permanent, linkable home.
Further Reading
- Keep a Changelog: The Format Explained (and When to Outgrow It)
- Semantic Versioning Explained: What MAJOR.MINOR.PATCH Actually Tells Your Users
- Release Candidate (RC): What It Means and How It Differs from Alpha, Beta, and GA
- Conventional Commits Cheat Sheet: Types, Examples, and Commit Message Best Practices
- What AI Coding Tools Actually See When They Read Your Changelog
Frequently Asked Questions
What is API deprecation?
API deprecation is the act of telling developers that an API, a version, an endpoint, or a field is no longer recommended and is scheduled to be replaced or removed. The deprecated thing keeps working during the deprecation period. Deprecation is a warning with a date attached, and the removal itself is a separate, later step usually called sunset or retirement.
What is the difference between deprecating and sunsetting an API?
Deprecating an API means announcing that it should no longer be used while it still works exactly as before. Sunsetting, also called retiring, is the moment it stops responding. RFC 8594 describes these as two stages, and RFC 9745 requires the sunset date to be no earlier than the deprecation date.
What are the Deprecation and Sunset HTTP headers?
They are response headers that tell API clients about a deprecation in a machine-readable way. The Deprecation header is defined in RFC 9745, a Standards Track RFC published in March 2025, and carries the date the resource was or will be deprecated, for example Deprecation: @1796083200. The Sunset header is defined in RFC 8594, an Informational RFC from May 2019, and carries the HTTP date after which the resource is expected to stop responding.
How much notice should you give before deprecating an API?
Published policies from large API providers sit between 12 and 24 months. GitHub supports a REST API version for at least 24 months after the next version ships, Shopify supports each quarterly version for at least 12 months with at least nine months of overlap, and IBM Security Verify gives 12 months of notice. A smaller API can give less, but the window should be written down in the docs before the first deprecation is announced.
What should an API deprecation policy include?
A deprecation policy should define which changes count as breaking, the minimum notice period before anything is removed, the channels a deprecation is announced on, the signals sent in API responses such as the Deprecation and Sunset headers, what a request receives after the sunset date, and the exceptions for security or legal emergencies. It should be a public page linked from the API reference.
What counts as a breaking change in an API?
GitHub's REST API documentation lists removing an operation, removing or renaming a parameter or response field, adding a required parameter, making an optional parameter required, changing a parameter or field type, removing enum values, adding a validation rule to an existing parameter, and changing authentication or authorization requirements. Additive changes such as new operations, optional parameters, and response fields are treated as non-breaking.
Ready to put this into practice?
Your changelog shouldn't be an afterthought.
ReleasePad makes it easy to publish great release notes — from a public changelog page to an in-app widget, GitHub integration, and analytics. Free to get started.
Get started — it's free