API changelogs: announcing changes developers will actually see

An API changelog has a harder job than a product changelog: the audience isn't a person glancing at a "what's new" popover — it's a developer who integrated eighteen months ago, stopped thinking about you, and whose code will break silently if you change something it depended on. This guide covers what to announce, where, in what format, and how to make the whole thing a habit instead of an incident postmortem.

Why API changes are different

Three things make API communication unforgiving:

  • Consumers are programs. A human adapts to a moved button in seconds. A program does exactly what it did yesterday until it errors — usually at 3am, in someone's production, with your name in the stack trace.
  • Nobody visits your dashboard. A working integration is one nobody looks at. Announcements that only live on a page people must remember to check reach almost no one who matters.
  • Blast radius is invisible. You can see which endpoints get traffic, but not which response fields some consumer's parser depends on. Per Hyrum's Law, with enough users, every observable behavior of your API is somebody's load-bearing wall.

What counts as breaking (it's more than you think)

Everyone knows removing an endpoint or renaming a field is breaking. The dangerous ones are the changes that feel additive:

  • Adding a field to a response — safe for tolerant parsers, breaking for strict ones (and for consumers who mirror your schema into a typed model with additionalProperties: false).
  • Adding a new enum value — every switch statement on that enum without a default case now has an unhandled branch.
  • Tightening validation — requests that used to succeed now 400. The clients sending them were "wrong", but they were working.
  • Changing defaults, limits, or ordering — same endpoint, same schema, different behavior. The worst kind, because nothing errors; results just change.
  • Meaningfully changing latency or rate limits — timeouts and retry loops were tuned against the old numbers.

The honest rule: if a reasonable client could notice, announce it. Announcing a change that turns out to affect nobody costs one paragraph. Not announcing one that affects somebody costs a trust you don't get back.

Publish a deprecation policy before you need one

The single highest-leverage document an API team can write is one page stating:

  • The support window — "deprecated endpoints keep working for at least N months after the deprecation notice" (6–12 months is typical; pick what you can keep).
  • Where notices appear — the changelog URL, the feed, response headers.
  • What "deprecated" means concretely — still works, gets security fixes, gets no new features, has a published successor.

Written before any specific fight, it's policy; written during one, it's spin. It also disciplines you: a sunset window you published is one you'll design around.

Announce in-band, not just on a page

Because nobody rereads your docs, put the signal in the response itself:

  • Deprecation and Sunset headers (RFC 8594) on deprecated endpoints, with a Link header pointing at the changelog entry. Tooling increasingly surfaces these automatically.
  • A warning field or header on soon-to-change behavior — consumers who log warnings will find it in their own logs, which they do read.
  • Machine-readable changelog feeds — an RSS/JSON feed of API changes lets consumers wire your changelog into their Slack. That converts your announcement channel from "page they must remember" to "notification they already get".

The entry template

Every API change entry should answer five questions in order — affected surface first, because developers scan for "is this me?":

Breaking: `status` field values change on GET /v1/jobs — action needed by Nov 3

WHO'S AFFECTED  Anyone reading `status` on job objects.
WHAT CHANGES    `status` gains a new value `queued` (previously jobs
                appeared as `pending` until execution started).
WHY             Distinguishes accepted-but-waiting from actively-starting jobs.
ACTION          Treat unknown status values as `pending`, or add `queued`
                to your handling. Clients with exhaustive enum checks must update.
TIMELINE        Deprecation headers live today · new value returned from Nov 3.

Tag entries (breaking / new / fix / announcement) so integrators can filter to the only category they truly must read. For the full deprecation playbook — announce three times, never move dates earlier — see announcing breaking changes.

Versioning is communication too

Your version scheme is a promise about what changes without warning (semver in plain English covers the mechanics). Two schemes work well for HTTP APIs:

  • Path major versions (/v1/, /v2/): breaking changes only ever land in a new path; the changelog's job is additive changes and the migration story between majors.
  • Dated versions (Stripe-style 2026-07-26 pinned per account): each breaking change creates a new date; the changelog is the version history — every dated entry documents exactly what that version changed.

Either way, the changelog carries the story. "We use semver" without a changelog is a promise with no receipts.

Make it a pipeline, not a chore

API changelogs go stale because they're manual. Wire them into the release path instead: diff your OpenAPI spec in CI (tools like oasdiff flag breaking changes mechanically — a great tripwire, though a lousy author: it can't tell you why or what to do about it), draft the entry from the diff, then have a human do the two-minute curation pass (the generated-draft rule).

Wakelog is built for exactly this shape: post the entry from CI with one curl or wakelog post --draft, schedule the change-day announcement with --at, and your consumers get a hosted page, RSS and JSON feeds to wire into their own alerts, and webhook mirrors to Slack or Discord — for free.

Start an API changelog — free   Next: announcing breaking changes →

Related guides

  • Announcing rate limit and quota changes: when the breaking change is a number
    Tighten a rate limit and no schema changes, no endpoint moves, no version bumps — every diff tool in the world reports nothing happened. Then the month closes, traffic peaks, and integrations that ran flawlessly for two years start throwing 429s at the exact moment their owners can least afford it. Limit changes are the API break nothing can detect, which makes the announcement the only interface you have.
  • Webhook and event payload changes: announcing new shapes to consumers who can’t pin a version
    An API consumer chooses when to call you, which version to ask for, and when to upgrade. A webhook consumer wrote a handler during integration week three years ago and hasn’t looked at it since — and whatever your producer sends tonight is what that handler receives, ready or not. Changing a payload you push needs different disciplines than changing an endpoint people call, starting with the fact that you — uniquely — hold a complete list of everyone who will break.
  • Vendor changelog monitoring: keeping up with what your dependencies change
    The flip side of every other guide here: reading changelogs, not writing them. Bots, feeds, in-band signals, severity triage, and a vendor register that outlives one person’s feed reader.

Last updated 2026-07-26 · All guides