API changelog: what to publish and who reads it

An API changelog is the dated record of every change a caller could notice, written for the people who integrate with the API rather than for the team that ships it. That audience makes it a different document from a product changelog: the reader is deciding whether their code still works next month. Most of them fail the same way, by being a filtered copy of an internal release feed, so a removed field sits next to a copy tweak with the same weight and neither gets read.

What is an API changelog?

It is the public, dated log of changes to an interface other people have written code against. The useful test for whether something belongs in it has nothing to do with how large the change was internally. It asks whether a correct caller, written last year and untouched since, could behave differently because of it. That test admits some very small changes and excludes some very large ones.

Everything below assumes the caller is outside the company and effectively unreachable except through this document. When the caller is another team down the hall, the calculus changes enough to need its own treatment; internal API changelogs covers what that audience needs instead.

How to write an API migration guide covers that last document in full; the short version here is that it’s what a breaking-change entry should link to rather than try to replace.

The five are separate documents with separate lifetimes. A deprecation notice is a promise with a date, and it belongs in the changelog too, but a changelog entry is written once and a deprecation is tracked until its sunset. Collapsing them is why sunsets get missed.

What belongs in a single entry?

Six things, and the first three are the ones usually missing. The change, stated in terms of the request or response rather than the internal component. Whether it breaks a correct caller. What the caller has to do, including “nothing”. The date it took effect. The version or versions affected. A link to the migration guide when one exists.

An entry that says “improved the accounts endpoint” fails all six. An entry that says “the accounts.type field now returns individual where it previously returned personal; existing values are unchanged for accounts created before 2 September; no action needed unless you compare the string” answers every one of them in a sentence.

Categorise entries by consequence, not by department. Three labels carry almost all the value: breaking, additive, and fixed. Semantic versioning already defines the first two precisely, and borrowing its definitions rather than inventing local ones means a reader who knows semver knows your labels. Keep a Changelog supplies a longer set if you want one, and its central rule applies here more strongly than anywhere else: the log is for humans, and a dump of commit subjects is not one.

How is an API changelog different from release notes?

Release notes describe what the product can now do. An API changelog describes what the contract now is. The same shipped work often produces an entry in both, worded differently, because the audiences need different things from it: a new export format is a feature to a user and a new enum value to a caller who switches on that field.

The practical consequence is that the two cannot be the same feed with different styling. A caller subscribing to everything you ship will unsubscribe, and then miss the breaking change. If you publish one feed, filter it; if you publish two, make the API one narrower and never let a marketing entry into it. We look at both shapes side by side in changelog vs release notes.

Where should an API changelog live?

Next to the reference documentation, on a stable URL, with every entry individually addressable by a fragment or its own path. Callers link to entries in incident reviews and internal tickets, and an entry that cannot be linked to gets pasted as a screenshot instead.

Publish it as machine-readable output as well as a page. A JSON feed following the JSON Feed spec or an RSS feed costs nothing once the entries are structured, and it is what lets a customer put your changes into their own release process. This is also the part that decides whether anyone builds on it. GitHub documents its REST API versions alongside the reference for the same reason: the version policy is part of the interface.

What does a good entry look like in practice?

Three entries from the same week, in the shape described above:

2026-09-02  Breaking  v2
  `POST /invoices` now rejects a `currency` that does not match the customer's
  account currency, returning 422 instead of silently converting. Callers that
  relied on conversion must send the account currency. Affects v2 only; v1 is
  unchanged until its sunset on 2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` gains a `settled_at` timestamp, null until the invoice settles.
  No action needed. Clients that reject unknown fields should be updated.

2026-08-31  Fixed  v2
  `GET /invoices?status=` returned an empty page instead of a 400 for an
  unknown status. It now returns 400 with the accepted values. Callers passing
  a typo previously saw no results and now see an error.

The third one is the kind most often left out, because internally it is a bug fix. To a caller who built a retry around that empty page, it is a behaviour change, and the entry is what stops the support ticket. The label says fixed and the body says what a caller might notice, which is the distinction that keeps the log honest without inflating every fix into a breaking change.

How do callers subscribe to it?

Give them more than one channel, because they have different jobs. A feed for the developer who wants everything. Email for the person who only wants breaking changes. Response headers for the code itself, which is the only subscriber that never forgets to check: the Sunset header defined in RFC 8594 puts the retirement date in the response, where a client library can log it.

The channel most teams skip is the direct one. If a caller used the field you are changing last week, you know who they are, and an email to those accounts is worth more than any amount of broadcast. This is the same discipline as closing the customer feedback loop, applied to a change nobody requested: the people affected get told individually, and everyone else gets the feed. A webhook is a fourth channel with its own failure mode worth knowing before you rely on it: webhook changelogs covers why a payload change there breaks silently, with no caller to reject the new shape.

How do you write an entry for a breaking change?

Lead with the breakage, not the reason. A caller scanning ten entries needs to know in the first clause whether this one costs them work. Then the date, the affected versions, the migration, and the deadline if the old behaviour is going away rather than changing.

Put the same content in the deprecation notice, the response header and the direct email, worded consistently, and give all four the same date. Drift between them is the failure that turns a planned change into an incident, because the caller who read one of them acts on the wrong date. What is a breaking change covers the decision itself, and how to deprecate an API covers the timeline that follows.

In Changeloop, an API change becomes an entry when the pull request merges, a person edits and approves the draft, and the entry publishes to the feed and the widget at the same moment a caller whose widget feedback became the GitHub issue the pull request closes is told on that issue. The reviewing step is the part that matters here: an API changelog is a contract document, and no draft should reach a caller without a human having read it.

FAQ

Does every API change need a changelog entry? Every change a correct caller could notice does, including ones you consider internal. Changes with no observable effect on the request or response do not, and adding them trains readers to skim.

Should the API changelog live in the docs or on the marketing site? In the docs, next to the reference. The reader is usually already there, and a changelog on the marketing site tends to acquire an audience it was not written for.

How far back should it go? Indefinitely. Entries are cited in incident reviews years later, and a truncated log breaks those links. Paginate rather than prune.

Do I need a separate changelog per API version? No, one log with a version field per entry is easier to read and to search. Filtering by version is a feature of the page rather than a reason to split the document.

The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.

Related on changeloop: Developer docs, Changelog examples