Chapter 09 of 12
API Changelogs and Migration Guides
What belongs in a changelog entry, how release notes differ from it, and how to write a migration guide that reaches the consumer at the moment they need it.
A changelog is the interface to your interface. It is where a consumer finds out whether the release you just shipped is something they have to care about, and most of them are written as though nobody will ever read them under pressure.
What a consumer is actually doing
Picture the reader for a moment. They maintain an integration they have not touched in five months, they have just received an email saying a new version shipped, and they have about ninety seconds before they move on.
They are answering one question, which is whether anything here affects them. Everything about the format follows from that. The classification comes first, the affected surface is named precisely, and the action is explicit. Prose that requires reading three paragraphs to find out that nothing changed for them is a failure even when every word is accurate.
The anatomy of an entry
| Element | Why it is there |
|---|---|
| Date and version | Lets a reader skip everything before their last upgrade |
| Classification | Breaking, added, changed or deprecated, scanned before anything else |
| The exact surface | The endpoint, the field, the parameter, named as it appears in the contract |
| What changed | Old behaviour and new behaviour, in that order |
| What to do | Migrate, do nothing, or act before a date |
A good entry can be read in one line and expanded when it matters. A bad one requires the reader to reconstruct which of your endpoints they use.
Changelog, release notes, migration guide
The three get conflated constantly, and each of them is written for a different reader with a different question.
The changelog is exhaustive and dated. Every contract change appears, including the ones that affect nobody, because a consumer scanning for their own endpoint needs completeness more than they need brevity.
The release notes are a narrative for one release. They say what the release is for, what is worth adopting, and what needs attention. They are allowed to be selective, and they are the wrong place to hide a breaking change.
The migration guide exists per breaking change, not per release. It is the longest of the three, it is the one that gets read at the worst possible moment, and it is the one that decides whether your deprecation was a courtesy or a nuisance.
All three live on the documentation site, so where they sit and how a reader reaches them is a structural question as much as an editorial one. The API documentation guide covers the pages around the changelog.
Generate what is mechanical
Half of a changelog is derivable. Comparing two contract versions produces every added endpoint, every removed field, every type change and every new enum value, with the classification already attached.
Generating that half has two benefits beyond the time saved. It never forgets an entry, which is the most common failure of a hand-written changelog, and it uses the same classification as your release gate, so the changelog and the pipeline cannot disagree.
The other half cannot be generated. A change in what a value means, a tightened validation rule, a different error for the same situation, and a performance characteristic your consumers relied on are all invisible to a diff. Somebody has to write those, and the generated half is what leaves them the attention to do it.
Reaching people who are not reading
A changelog is a pull channel, and the consumers most likely to break are the ones least likely to pull.
Three push channels close the gap. The Deprecation and Sunset headers described in deprecation and sunset reach a consumer's own monitoring without anybody reading anything. A direct message to identifiable consumers naming their integration reaches the team that has to act. An error response that names the change, at the moment something stops working, reaches the person debugging it.
That last one is underrated. When a request fails because of a change you made, the error body is the highest-attention documentation surface you will ever have, so link the migration guide from it.
Write the migration guide for a bad day
Assume the reader is annoyed, in a hurry, and unfamiliar with the endpoint they are fixing. Four sections cover it.
Name the replacement and link it. Show the old call and the new call complete and side by side, then list the response differences field by field. Finish with the part everybody omits, which is what has no equivalent and what to do instead.
Where a capability is going away with no replacement, say that in the first paragraph. A consumer who searches for twenty minutes before concluding the same thing will arrive in your support queue in a much worse mood.
In Routebase
Changelog entries are generated from the difference between two versions, with the same classification the release wizard uses. You review them, edit them, and publish them as a page in the documentation portal, so the changelog your consumers read comes from the contract rather than from somebody's memory of the sprint.
Release notes are part of the release itself, written in the wizard and visible to consumers in the documentation. A deprecation carries its own migration guide, which is rendered on the portal page of the affected endpoint together with the sunset date and a link to the successor. Where consumers of a specification are known, the owners of dependent services can be notified directly. The Changelog guide covers the generated pages, and the Spec Versioning guide covers release notes.
Frequently asked questions
What should an API changelog contain?
Every entry needs a date, a version, a classification of the change as breaking or additive, the affected endpoint or field, and an action for the reader. A changelog that lists what you did without saying what a consumer must do is a work log. The classification is the part consumers scan for, so it belongs at the front of the entry rather than in the prose.
What is the difference between release notes and a changelog?
A changelog is a complete, dated record of contract changes, written for a consumer checking whether anything affects them. Release notes are a narrative summary of one release, written for someone deciding whether to upgrade. The changelog has to be exhaustive and the release notes have to be readable, which is why one is usually generated and the other written.
How do you write an API migration guide?
Name the replacement, show the old call and the new call side by side, state what changed in the response, and be explicit about anything that has no equivalent. The missing-equivalent section is the one people skip and the one that generates support tickets, because a consumer who cannot find a replacement assumes the migration is impossible.
Should an API changelog be generated or written by hand?
Generate the structural half from the diff between two contract versions, since that half is mechanical and it is the half people forget. Write the semantic half by hand, because a change of meaning behind an unchanged shape is invisible to any generator. The two together are complete, and either one alone is not.
Last reviewed by The Routebase Team.