What should API release notes include?

Every entry needs the date, the affected version, a change-type label (breaking, added, changed, deprecated, removed), what changed in concrete terms, who is affected, what action to take, and the deadline if there is one. Breaking changes additionally need a link to a migration guide. If a reader can't tell within ten seconds whether they need to act, the entry has failed.

What counts as a breaking change in an API?

Removing an endpoint, removing or renaming a parameter or response field, adding a new required parameter, making an optional parameter required, changing a field's type, removing enum values, or changing authentication requirements — that's GitHub's documented list, and it's a good default. Additive changes like new endpoints, new optional parameters, and new response fields are generally safe, which is why well-built clients must tolerate unknown fields.

How much notice should I give before a breaking API change?

The published policies of major API providers cluster between 12 and 24 months: GitHub supports each REST API version for at least 24 months after the next one ships, Shopify supports each quarterly version for at least 12 months, and Twilio's SDK lifecycle allows roughly 24 months from a new major release to end-of-life. Small teams can give less, but anything under 90 days for a paid product is asking for churn.

What are the Deprecation and Sunset HTTP headers?

They are standardized response headers that tell API clients about upcoming changes in a machine-readable way. The Deprecation header (RFC 9745, published March 2025) signals that a resource is or will be deprecated, and the Sunset header (RFC 8594) announces the date the resource is expected to stop working. GitHub sends both as an API version approaches retirement, and clients or monitoring tools can alert on them automatically.

Should APIs use semantic versioning?

Most large HTTP APIs don't. Stripe uses named date-based versions, GitHub and Shopify use calendar dates, and Twilio has kept the same URL version since 2010. Semver works well for libraries and SDKs, where a package manager resolves versions — but for a hosted API, date-based versions plus a clear support window communicate more, because the version name itself tells consumers how old their integration is.

Can I automate breaking-change detection for my API?

Yes. If you maintain an OpenAPI spec, tools like oasdiff and OpenAPITools' openapi-diff compare two spec versions and flag breaking changes automatically — oasdiff has a dedicated 'breaking' command and can generate a changelog between versions. Pair that with conventional commits (a ! or BREAKING CHANGE footer) and your release notes can flag breakage before a human even reviews the diff.

How to Write API Release Notes

A UI change your users don’t like costs you a complaint. An API change your users didn’t see coming costs them an outage — and costs you the account. Here’s how the teams that run the internet’s biggest APIs write their release notes, and what you can copy from them.

API release notes are a different discipline from product release notes. The reader of your product changelog is a person who might be delighted, might be indifferent. The reader of your API changelog is a person whose code calls yours in production, often on a schedule, often without a human watching. When you change something they depend on, the failure doesn’t show up as mild disappointment — it shows up as a pager going off.

That asymmetry should drive everything about how you write them. This guide covers what counts as a breaking change, how Stripe, GitHub, Shopify, Twilio, and Slack actually communicate changes, the two HTTP headers that make deprecations machine-readable, and the notice windows the industry has converged on — plus the cautionary tales of what happens when you skip all of this.

First, Agree on What “Breaking” Means

Most API changelog failures start earlier than the writing: the team never defined which changes require warning and which don’t. The good news is you don’t have to invent this. The biggest API companies publish their definitions.

GitHub documents its breaking-change list explicitly: removing an entire operation; removing or renaming a parameter or response field; adding a new required parameter; making an optional parameter required; changing a parameter or field type; removing enum values; adding a new validation rule; changing authentication or authorization requirements. Everything additive — new endpoints, new optional parameters, new response fields, new enum values — ships to all supported versions without ceremony.

Stripe publishes the inverse: what it considers backward-compatible and will ship without a new major version. That list includes adding new API resources, adding optional request parameters, adding properties to existing responses, changing the order of response properties, and adding new event types — with the explicit note that webhook consumers must gracefully handle unfamiliar event types.

Google’s AIP-180 goes further and is worth reading whole: compatibility isn’t just wire format, it’s semantics. Default values must not change. Field types must not change even when the wire encoding would survive it. And “APIs must not change visible behavior in ways that are likely to break reasonable user code” — even behavior you never documented.

The practical takeaway: write your own one-page definition, publish it next to your API docs, and label every changelog entry against it. The label — Breaking, Added, Changed, Deprecated, Removed — is the single highest-value word in an API release note, because it’s the word that tells a reader whether to keep scrolling or open a ticket. (This taxonomy comes straight from the Keep a Changelog format, which maps to APIs unusually well.)

How the Big APIs Version and Communicate

There’s no single right model, but every serious one shares a property: the consumer chooses when to absorb a breaking change, not the provider.

Stripe: pinned versions with named releases. Your Stripe account is pinned to the API version of your first request, and it stays there until you deliberately upgrade. Major releases carry plant names and dates — the current one is 2026-06-24.dahlia — and only major releases contain breaking changes; monthly releases are backward-compatible by policy. Two details worth stealing: you can override the version per-request with a header to test an upgrade before committing, and after upgrading you get 72 hours to roll back from the dashboard. That rollback window converts upgrades from a cliff into a doorway.

GitHub: calendar versions with a 24-month floor. GitHub’s REST API versions are dates (2022-11-28, 2026-03-10), sent via the X-GitHub-Api-Version header. When a new version ships, the previous one is supported for at least 24 more months, and the docs list the scheduled end-of-support date. Requests to a removed version return 410 Gone — a clean, unambiguous failure rather than silently different behavior.

Shopify: quarterly rhythm. New API versions land every three months, each supported for at least 12 months, guaranteeing at least nine months of overlap to migrate. Two mechanisms stand out. Requests to a retired version aren’t dropped — they’re served by the oldest still-supported version, with an X-Shopify-API-Version response header so you can detect that it happened. And enforcement has teeth: apps still calling removed resources past the deadline get delisted from the App Store. Deprecations are announced in the developer changelog with migration guidance, surfaced in per-app API health reports, and — for imminent breaking changes — sent directly to each app’s emergency developer contact.

Twilio: (almost) never break, extend when in doubt. Twilio’s core REST API still answers at the 2010-04-01 version path — sixteen years without forcing a migration. When it does sunset something, the runway is long and flexible: the 2008-era API got roughly 20 months of communicated end-of-life notice, and the Notify API’s EOL date was extended twice — ultimately by more than two years — while migration paths matured.

Slack: a changelog of the future. Alongside its dated changelog with a dedicated “breaking change” tag, Slack maintains a page of scheduled changes — things that will change, with dates, before they change. That page is doing the real work: an API changelog that only reports the past is telling developers about outages they’re already having.

If you run a small API, you won’t replicate all of this. But the minimum viable version is achievable by anyone: date-stamped versions, a written support window, a changelog with change-type labels, and a “scheduled changes” section.

The Anatomy of a Good API Changelog Entry

Structure every entry to answer five questions in order:

What changed? One concrete sentence. “The customer.email field is deprecated in favor of customer.primary_email” — not “we’ve improved our customer model.”
Is it breaking? The label, up front, visually distinct.
Who’s affected? “Anyone reading customer.email from the /v2/customers response or the customer.updated webhook.”
What do I do about it? The exact migration step, or “no action required.”
By when? The deadline, as a date, not “in the coming months.”

A worked example:

2026-07-10 — DEPRECATED
customer.email replaced by customer.primary_email

Affects: GET /v2/customers, customer.* webhooks
Action: read primary_email; email remains populated until sunset
Sunset: 2027-07-10 (12 months) — migration guide →

Notice what’s absent: adjectives, apologies, marketing. API release notes are the one changelog genre where personality is a liability. Save the voice for your product release notes; here, precision is the brand.

Deprecation Done Right: Signals, Not Just Announcements

A changelog post is necessary but not sufficient — it only reaches developers who read it. The best deprecation programs layer machine-readable signals on top, so the warning reaches the code itself:

The Deprecation header (RFC 9745). Standardized in March 2025, this response header carries the date a resource became (or will become) deprecated. Deprecation changes nothing about behavior — it’s purely a signal — and the spec defines a deprecation link relation for pointing at documentation.

The Sunset header (RFC 8594). The companion header announces when the resource is expected to stop responding entirely. The spec requires the sunset date to be no earlier than the deprecation date: first you warn, then you turn off.

GitHub sends both as an API version approaches retirement. The payoff is that clients, API gateways, and monitoring tools can alert on these headers automatically — your deprecation notice fires inside your customer’s observability stack, not just on a web page they visit twice a year.

Layer the channels in this order:

Changelog entry the day the deprecation is decided, with the sunset date
Headers on every affected response from that day forward
Docs updated with a deprecation banner and migration guide
Direct outreach to accounts still calling the deprecated surface as the deadline approaches — Shopify’s “emergency developer contact” pattern
Reminder entries in the changelog at sensible intervals; Twilio’s changelog is full of “reminder: end of life for…” posts, and that repetition is a feature

And instrument the other direction too: if you can’t measure who is still calling the deprecated endpoint, you can’t know whether your communication worked. The teams that extend deadlines gracefully (Twilio, Slack) can do it because they’re watching real usage numbers fall — or not fall — as the date approaches.

How Much Notice? What the Industry Actually Gives

Published policies and observed practice, as of mid-2026:

Provider	Notice / support window	Source of the number
GitHub REST API	≥ 24 months per version	Published policy
Twilio (SDK lifecycle)	~24 months (12 support + 12 deprecated)	Published lifecycle
Twilio (2008 API retirement)	~20 months	EOL notices
Shopify	≥ 12 months per version, ≥ 9 months overlap	Published policy
Slack (`files.upload` retirement)	~10 months	Changelog dates
Stripe	No forced sunset — versions stay pinned until you upgrade	Published policy

The pattern: a year is the credible floor for a paid API, two years is the standard the biggest platforms hold themselves to. If your API is younger and your customer base smaller, you can move faster — but publish the window before you need it. A notice period announced during a crisis reads as a countdown; one published in your docs reads as a contract.

When It Goes Wrong

The most instructive API-communication failures of the past decade weren’t subtle engineering mistakes — they were notice-period mistakes.

Twitter, February 2023: the developer account announced that free API access would end “starting February 9” — in a tweet posted February 2. Seven days’ notice for every free integration on the platform. The deadline slipped repeatedly, which somehow made it worse: developers couldn’t plan around the original date or trust the new ones.

Reddit, 2023: API pricing announced in April, effective July 1. Apollo — one of the most popular third-party clients — learned its new bill would be roughly $20 million a year about a month before enforcement, announced shutdown for June 30, and more than 8,000 subreddits went dark in protest. The technology didn’t break anything; the runway did.

Heroku, 2022: about three months between announcing the end of free dynos and Postgres and the November 28 removal date. Better — but the episode is remembered as an ending, not a transition, partly because so many integrations and tutorials had nowhere to point.

The common thread: in every case the change itself was within the provider’s rights. What turned each one into a trust crisis was that the communication window was shorter than the integration lifecycle it was breaking. Your release notes can’t make an unpopular change popular — but a long, honest, well-signaled runway is the difference between “they’re raising prices” and “they broke my product.”

Automate the Detection, Not Just the Writing

Two kinds of automation make API release notes materially more reliable:

Spec diffing. If you maintain an OpenAPI spec, oasdiff compares two versions and flags breaking changes with a dedicated breaking command — it can generate the changelog skeleton for you. OpenAPITools’ openapi-diff does the same comparison. Run one in CI and a breaking change can’t reach production unannounced, because the pipeline knows before the reviewer does.

Commit conventions. If your team writes conventional commits, breaking changes are already marked in the history — the ! suffix or BREAKING CHANGE: footer. That structure flows straight into automated release notes from your commits, with the breaking items pre-flagged for the prominent treatment they need.

One more audience to write for: AI coding assistants. When a developer’s integration breaks, their first move in 2026 is increasingly to ask Cursor or Claude why — and those tools answer by reading your changelog. A dated, labeled, machine-readable changelog means the AI can say “the field was renamed in the June release, here’s the migration” instead of hallucinating an answer from stale training data. Publishing your API changelog in Markdown at a stable URL is the cheapest developer-experience win available this year.

The Checklist

Before you ship an API change, your release note should have:

A change-type label (Breaking / Added / Changed / Deprecated / Removed)
The affected version, endpoints, and fields — by name
Who’s affected and what to do, in one line each
The sunset date (for deprecations), as an actual date
A migration guide link (for anything breaking)
Deprecation and Sunset headers on the affected responses
A plan for reminders and direct outreach to remaining callers

Precise, labeled, dated, repeated. That’s the whole genre. If you want the starting scaffold, our release notes templates include an API-specific one.

How to Write API Release Notes (and Communicate Breaking Changes)