How to write an API migration guide
5 min read
An API migration guide is the document that turns a breaking change from an outage into a checklist: what changed, what to do about it, and by when. A changelog entry can name a breaking change in two sentences; a migration guide is what a caller actually opens when those two sentences say “this breaks you” and they need to know exactly what to edit. Publishing the entry without the guide is how a caller learns about a breaking change from a support ticket instead of from the document written to prevent one.
What is an API migration guide?
A step-by-step document that takes a caller from the old shape of an API to the new one, written for someone who has code to change, not someone deciding whether to adopt the API at all. That distinction matters: a migration guide assumes an existing integration and existing production traffic, so it has to cover rollback, partial migration, and how to tell whether the migration succeeded, none of which a first-time integration guide needs to address.
| Document | Assumes | Answers |
|---|---|---|
| Migration guide | An existing integration | How do I move from the old shape to the new one? |
| Changelog entry | Nothing, just that the reader checks in | What changed, and when? |
| API reference | Nothing, or a first integration | What does this endpoint do? |
| Deprecation notice | An integration using the old thing | When does this stop working? |
A migration guide usually sits between the last two: a deprecation notice starts a clock, and the migration guide is what a caller follows before that clock runs out.
When does a change need a migration guide, and not just a changelog entry?
When there is more than one step between the old behavior and the new one, or when the change touches enough call sites that a caller benefits from a worked example over a description. What is a breaking change, and how to ship one covers the test for whether a change is breaking at all; once the answer is yes, the second question is whether the fix is a one-line edit or a genuine migration. A field rename a caller can handle from the changelog entry alone. A change to authentication, pagination, or error handling almost always earns a guide, because the correct replacement code isn’t obvious from a one-sentence description.
What does a migration guide need to contain?
Five things, and skipping any one of them is what turns a guide into a page a caller reads once and then falls back to trial and error. The old code, shown as it would actually appear in a caller’s project. The new code, shown the same way, not as an abstract description of the difference. What breaks if nothing changes, stated plainly, because “nothing” is a valid and common answer that a caller still needs to hear explicitly. A way to verify the migration worked, such as a response field or a status code to check for. And a timeline: when the old behavior stops working, and whether both shapes are available in the meantime.
## Migrating currency fields from float to integer (v3.0.0)
Before:
{ "amount": 19.99 }
After:
{ "amount": 1999 } // smallest currency unit (cents)
What changes: `amount` is now an integer in the smallest unit of the
account currency. Code that reads `amount` as a float will read a
value 100x too large from the day you move to v3.
Verify: after migrating, a $19.99 charge should read `amount: 1999`,
not `amount: 19.99`.
Timeline: v2 keeps returning floats until 2027-01-15. v3 returns
integers from launch. Both versions are live now.Every one of those five things answers a question a caller would otherwise have to guess at or ask support to answer, which is the actual cost a migration guide is saving.
Who should write it, and when?
Whoever designed the change, at the same time the change ships, not a support team reconstructing it from tickets after callers start asking. The person who made the decision knows which parts of the old behavior nobody should have depended on and which parts were an accidental contract; a guide written later by someone without that context tends to either over-explain the obvious or miss the one edge case that actually breaks people. The guide and the changelog entry that announces the breaking change should ship together, with the entry linking to the guide rather than restating it.
How does this relate to versioning and the API changelog?
Directly: a migration guide is the detailed version of what a MAJOR entry in semantic versioning and your changelog only summarizes in a sentence. The changelog entry says a change is breaking and roughly what changed; the migration guide is the link that entry should carry. API changelog: what to publish and who reads it lists the migration guide as one of five documents an API maintains, each answering a different question; this is the one that answers “how do I actually move from A to B,” and it earns its own page precisely because that answer is usually too long for a changelog entry to hold.
How long should a migration guide stay published?
At least as long as the old behavior is reachable, and ideally after that too. A caller migrating eighteen months late, after ignoring three deprecation notices, still needs the guide, and deleting it the day the old behavior is switched off only guarantees that the caller who needed it most can’t find it. Keep it at a stable URL and update the timeline section rather than retiring the page. Stripe’s own upgrade guide is a public example of the pattern: one page, kept current release after release, rather than a new document per version that goes stale the moment the next one ships. Your own guide belongs somewhere just as findable, next to the docs a caller is already reading rather than buried in a blog archive.
FAQ
Does every breaking change need a migration guide? No. A change a caller can fix from the changelog entry alone, like a single renamed field with an obvious replacement, doesn’t need a separate guide. A change that touches multiple call sites or requires a worked example does.
Should a migration guide live with the API docs or in the changelog? With the docs, linked from the changelog entry. The changelog entry is what a subscriber sees first; the guide is what they need once they’ve decided to act on it, and it belongs next to the reference material a caller is already using.
What’s the difference between a migration guide and a deprecation notice? A deprecation notice states that something is going away and by when. A migration guide is the instructions for what to do about it. A deprecation notice without a linked migration guide tells a caller there’s a deadline without telling them how to meet it.
Should old and new behavior both be documented during a migration window? Yes, on the same page if possible, so a caller can see exactly what changed rather than piecing it together from two separate documents written at different times.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.