An API changelog is read by people whose code will stop working, which is why it needs three things a product changelog can leave out: the exact symbol that changed, the calendar date the old behaviour ends, and a feed a machine can poll. An end user meets a change on a screen and adapts in the moment. A consumer of an API meets it as a failed request in production, often weeks after the announcement, and everything they need to prevent that has to be in the entry.
A consumer of an API is a program somebody wrote months ago and has not looked at since. It sends the same request every hour and parses the same fields out of the response. A renamed field, a stricter validation rule, a removed enum value or a changed default breaks it silently or loudly, but always without a human in the loop to notice the wording of an announcement. That is the audience an API changelog is written for: not a reader browsing what is new, but a maintainer trying to work out whether last night's failure was theirs or yours.
| What an API consumer needs | Why an end user does not | Where it belongs |
|---|---|---|
| The exact symbol: endpoint, field or enum value | An end user has no code that names it | The entry title and its first line |
| A calendar removal date | An end user is migrated by the interface itself | The deprecation entry, repeated in the reference docs |
| The replacement, named precisely | An end user sees the replacement on screen | The same entry, next to the deprecation |
| A machine-readable feed of entries | An end user reads the page when they visit | An RSS or JSON feed beside the page |
| A stable link per entry and per version | An end user rarely cites one entry | Anchors on entries, headings on versions |
| A record when a published date moves | An end user never saw the first date | A new entry, not a quiet edit to the old one |
An API entry that says "improved metrics reporting" is unreadable by the audience it was written for. Buffer's public API changelog shows the opposite habit: entries name the type and the field, such as the replies value of the post metric enum, state the reason the field is deprecated,
Entries that open with "we've added" put the team in the subject position and leave the reader to translate. The repair is grammatical: make the thing the reader controls the subject of the sentence, and delete the team from it.
Market4 turns one release note into a changelog page, a blog post, a mail-out and a week of social posts — and then tells you which of them brought anyone back.
The habit that makes symbol naming work is writing the entry from the response, not from the pull request. A consumer never sees the internal module that changed; they see a field appear, disappear or change type. Describing the change in the vocabulary of the payload is what makes an entry searchable by the person who needs it.
Deprecation dates move, and the way a changelog handles that is a test of whether it can be trusted. Buffer's changelog records a set of metric fields whose removal date moved from 31 July 2026 to 1 December 2026, and it records the move as its own entry rather than editing the original announcement into a new shape. That is the correct handling: a consumer who read the first entry and scheduled work against the first date needs to be told the date changed, and a silent edit reaches nobody who already read the page.
The same rule applies in the other direction. A date that is brought forward is a more urgent entry, not a smaller one, and it should say plainly that the window shortened. Changelog entries are read once; the version a consumer has in their notes is the version that was published on the day they looked.
A page is a thing a person visits when they remember to. A feed is a thing a build can watch. Publishing an API changelog with an RSS or JSON feed alongside the page lets a consumer subscribe in a reader, pipe entries into a team channel, or check for new deprecations as part of their own release process. This product serves a changelog RSS feed next to the public changelog page for exactly that reason, and the feed address belongs in the API documentation rather than being left to be discovered.
The audience differs, so the content does. A product changelog is read by people who will see the change in the interface and adapt on the spot. An API changelog is read by maintainers of code that will keep sending the old request until somebody edits it. That audience needs the exact symbol that changed, the calendar date the old behaviour ends, the named replacement, and a feed their tooling can watch.
The symbol being deprecated, written as it appears in the payload; the reason, in one line; the replacement, named precisely; and the date the field or endpoint stops working. The date is the part most often omitted and the part consumers need most, because it is what lets them schedule the migration rather than discovering it from a failure in production.
Yes, or another machine-readable form. A changelog that exists only as a page is checked when somebody remembers; a feed can be subscribed to in a reader, forwarded into a team channel, or polled as part of a release process. Publish the feed address in the API documentation itself, because a feed nobody can find is the same as no feed.
Publish a new entry saying the date moved and in which direction, and leave the original entry intact. Consumers read a changelog once and act on what it said that day, so editing the old entry silently updates nobody. If the window has been shortened, say so in the title: a consumer who scheduled work for the original date needs the change to be as visible as the deprecation was.
A breaking change is the one entry a reader cannot skim. It has to name what stops working, the date it stops, and the replacement — and no common changelog standard gives it a category of its own, so the title and the body carry it.
Somebody deciding whether to buy your product reads the changelog for something your marketing pages cannot tell them: whether anyone is still working on it, and what happens to them when something changes.
