When an API releases a new version, every developer using it has to update their code. If they only get a changelog entry that says “pagination now uses cursors,” then they’ll have to figure things out themselves. Some of them will get it right, but others might not.
This is why developers need an API migration guide. It tells them what has changed, what they need to update in their code, and how long they have to do it.
In this tutorial, you’ll learn how to write an API migration guide from start to finish. We’ll use a sample Inventory API that is moving from v1 to v2 and write the guide together. By the end, you’ll have a finished guide and a structure you can reuse for other APIs.
This tutorial is for technical writers, developers who document their own APIs, and DevRel folks who need to explain API changes to other developers.
Table of Contents
- Prerequisites
- What is an API Migration Guide?
- What Counts as a Breaking Change?
- How to Write a Migration Guide for the Inventory API
- What Are the Most Common Mistakes in API Migration Guides?
- Conclusion
Prerequisites
You don't need to be an API expert to follow along, but you need to understand these basic things:
- Basic knowledge of REST APIs: You should know what an endpoint is, what request headers do, and what status codes like 401 and 404 mean.
- Comfort reading JavaScript: The before-and-after code examples use JavaScript's
fetch()function. You won't need to run them, but you should be able to follow what each one does. - Familiarity with Markdown: You'll write the migration guide in Markdown, the same format most docs sites and GitHub READMEs use.
Note: The Inventory API is a sample API I made for this tutorial, so there's nothing to install or sign up for. All you need is a text editor.
What is an API Migration Guide?
An API migration guide is a document that shows developers how to move their code from one version of an API to another. It explains what changed, what they need to update, and the deadline for making those changes.
People usually mix up migration guides with changelogs and release notes because they all talk about changes. The difference is in what they're for.
A changelog records what changed, release notes announce what's new, and a migration guide tells developers what to update in their code because of those changes.
| Changelog | Release notes | Migration guide | |
|---|---|---|---|
| Purpose | Record every change in each version | Announce what's new in a release | Help developers update their code |
| Covers | All changes, big and small | Highlights and new features | Changes that need action from developers |
| Format | A list grouped by version | A short summary or announcement | Step-by-step instructions with code |
| Answers | "What changed?" | "What's new?" | "What do I need to do?" |
So if a developer reads your changelog and still doesn't know what to change in their code, that's a sign you need a migration guide. Most of the time, that happens when a release includes breaking changes.
What Counts as a Breaking Change?
A breaking change is any change to an API that can make existing code stop working without the developer changing anything. For example, if a change to an API stops someone's integration from working, that's a breaking change.
That's why API teams usually release breaking changes in a new major version, like moving from v1 to v2. Many teams follow Semantic Versioning (SemVer), a numbering system where a version like 2.4.1 has three parts (major, minor, and patch). The major number increases when a change breaks existing code, which is why you'll see APIs jump from v1 to v2 instead of v1.1.
| Part of the API | Breaking change | Non-breaking change |
|---|---|---|
| Endpoints | Removing an endpoint | Adding a new endpoint |
| Fields | Renaming, removing, or changing the type of a field, like a number becoming a string | Adding a new field to a response |
| Parameters | Making an optional parameter required | Adding a new optional parameter |
| Authentication | Changing how developers send their API key, like moving it from the URL to a header | Adding a new way to authenticate while the old way still works |
| Errors | Changing the way error responses are structured, like a text message becoming an object | Adding a new field to the existing error object, like a request ID |
| Pagination | Changing how results are split into pages, like page numbers becoming cursors | Raising the maximum number of items per page |
Some changes fall in between. For example, adding a new field to a response doesn't cause problems in most cases, but it can break apps that are set up to reject unknown fields. A new error status code can also catch developers off guard if their code only handles the old ones.
When you're not sure, treat the change as breaking and cover it in your guide.
When Do You Need a Migration Guide?
If a release only has non-breaking changes, then you don't need a migration guide. A changelog entry is usually enough. But once a release has even one breaking change, developers need to know what to update in their code. That's what the migration guide is for.
How to Write a Migration Guide for the Inventory API
Now that you know what a migration guide is and when you need it, it's time to write one. For the rest of this tutorial, you'll work with the Inventory API I mentioned earlier. It's a sample API that lets developers list items in their inventory, check stock levels, and add or remove stock.
The Inventory API is moving from v1 to v2, and v1 stops working on March 31, 2027. I've put the reference docs for both versions in a GitHub repo, so open v1-reference.md and v2-reference.md side by side. You'll be comparing them a lot in the first step.
Step 1: List and Classify Every Change
Before you write anything, you need a full list of what changed between the two versions. Any change you miss here won’t be in your guide, and developers will only learn about it when their code fails.
Start by comparing the two reference docs section by section. For example, here's the same request to remove 5 units of stock from an item in each version:
# v1 curl -X POST "https://api.example.com/v1/items/itm_204/adjust?api_key=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"qty": -5}' # v2 curl -X POST "https://api.example.com/v2/items/itm_204/adjust" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"quantity": -5}' This one request shows three changes:
- The base URL moved from
/v1to/v2. - The API key moved from the URL to an
Authorizationheader. qtybecamequantity.
Go through both docs like this and write down every difference you find, no matter how small.
For an actual product, don't rely on the docs alone, because they can be outdated. Check the changelog and pull requests too, and ask the engineers who built the new version to confirm your list. If both versions have an OpenAPI spec, a tool like oasdiff can compare them and flag breaking changes for you.
Once you have your list, put it in a table. For each change, record where it happens, whether it's breaking, and who it affects:
| # | Change | Where | Breaking? | Who it affects |
|---|---|---|---|---|
| 1 | Base URL changed from /v1 to /v2 | All endpoints | Yes | Everyone |
| 2 | API key moved from a query parameter to an Authorization header | All endpoints | Yes | Everyone |
| 3 | page and per_page replaced with limit and cursor | GET /items | Yes | Anyone who lists items |
| 4 | qty renamed to quantity in responses | GET /items, GET /items/{id} | Yes | Anyone who reads stock levels |
| 5 | qty renamed to quantity in the request body | POST /items/{id}/adjust | Yes | Anyone who adds or removes stock |
| 6 | Error responses changed from a string to an object with code and message | All endpoints | Yes | Anyone who handles errors |
| 7 | New 429 error when you send too many requests | All endpoints | Treat as yes | Anyone who sends lots of requests |
| 8 | New warehouse_id field in item responses | GET /items, GET /items/{id} | No | Anyone who wants to know where stock is |
| 9 | New optional reason field in the request body | POST /items/{id}/adjust | No | Anyone who wants to record why stock changed |
Notice that the qty rename shows up twice, once in responses and once in the request body. It's the same rename, but developers fix it in different parts of their code, so they’re listed as two separate changes.
Change 7 is an example of the in-between cases I mentioned earlier. A 429 error doesn't break anything on its own, but code that doesn't handle it can fail in ways developers won't expect, so I'm treating it as breaking.
With every change listed and classified, you now know what the guide needs to cover. Seven of the nine changes need action from developers, so they’ll be the main part of the guide.
Step 2: Outline the Guide and Write the Summary
The next thing to decide is how to organize the guide. Developers don't read migration guides from beginning to end like an article. They scan for what affects them, fix it, and then move on. So the structure should answer their questions in the same order they’d ask them.
Here's the outline I use for the Inventory API guide:
# Migrating from Inventory API v1 to v2 ## Summary ## Timeline ## Breaking changes ### Base URL ### Authentication ### Pagination ### Field rename: qty to quantity ### Error responses ### Rate limiting ## New features ## Migration checklist ## Test your migration ## Roll back The summary and timeline come first because they answer the two questions every developer has before anything else: "Does this affect me?" and "How long do I have?"
Breaking changes come next because they require action, and the new features come after them because developers can ignore those and their code won't break. The checklist, testing, and rollback sections are at the end, because developers need them after making their changes.
With the outline in place, write the summary. It should tell developers what changed, who it affects, and the deadline. Keep it in a few sentences.
For the Inventory API, it looks like this:
# Migrating from Inventory API v1 to v2 ## Summary Inventory API v2 changes how you authenticate, how you page through items, and how errors come back. It also renames the `qty` field to `quantity`. If your code calls any v1 endpoint, you need to update it before **March 31, 2027**, when v1 stops working. This guide walks you through each change with before-and-after code. ## Timeline | Date | What happens | |---|---| | Now | v2 is available. v1 still works, so you can migrate at your own pace. | | March 31, 2027 | v1 stops working. Requests to `/v1` endpoints will fail. | The deadline is in bold and appears in the first paragraph. If a developer reads only one sentence of your guide, it should be the one with the date in it.
Step 3: Document Each Change with Before-and-After Code
This is the main part of the guide, and it's where developers spend most of their time. For each breaking change, they want to know what changed and what to update in their code.
To keep things consistent, document every change using the same four sections:
- What changed
- Why it changed (only when the reason helps developers)
- Before and after code
- What you need to do
The authentication change is a good example, since every developer using the API will run into it:
### Authentication **What changed:** v2 no longer accepts your API key as a query parameter. Send it in the `Authorization` header instead. **Why it changed:** API keys in URLs can end up in server logs and browser history, where other people can see them. A header keeps the key out of those places. **Before (v1):** ```javascript const res = await fetch(`${BASE_URL}/items?api_key=${API_KEY}`); ``` **After (v2):** ```javascript const res = await fetch(`${BASE_URL}/items`, { headers: { Authorization: `Bearer ${API_KEY}` }, }); ``` **What you need to do:** Remove `api_key` from every request URL and send the key in the `Authorization` header. v2 rejects keys sent as query parameters. The "why" section is only two sentences, but it plays an important role. Developers don't like changing code that already works, so a lot of them wait until the last minute to migrate. When they see that the change keeps their API key safe, they have a clear reason to apply it now.
The Rest of the Changes
The other changes follow the same pattern, but not all of them need the same amount of detail here. A simple change only needs a sentence and a short code line. A change that affects how developers structure their code needs a full before-and-after example.
Some of the Inventory API changes are simple, so a line or two each is enough:
- Base URL: Every endpoint moved from
/v1to/v2. Developers update the base URL in one place. qtyrenamed toquantity: Developers rename the field wherever they read it from responses and wherever they send it in the request body.- New fields:
warehouse_idin responses andreasonin the adjust request body are optional additions. They go in the guide's "New features" section because skipping them won’t break anything.
Pagination and errors are different. Both change how developers write their loops and error handling, so they need full code examples.
Pagination
v1 used page numbers, so developers looped until they reached the last page. v2 uses a cursor, so they keep requesting pages until next_cursor comes back as null:
// v1: page numbers let page = 1; let totalPages; do { const res = await fetch( `${BASE_URL}/items?page=${page}&per_page=100&api_key=${API_KEY}` ); const body = await res.json(); saveItems(body.data); totalPages = body.total_pages; page++; } while (page <= totalPages); // v2: cursor let cursor = null; do { const query = cursor ? `limit=100&cursor=${cursor}` : "limit=100"; const res = await fetch(`${BASE_URL}/items?${query}`, { headers: { Authorization: `Bearer ${API_KEY}` }, }); const body = await res.json(); saveItems(body.data); cursor = body.next_cursor; } while (cursor); Errors and rate limits
In v1, error was a string. In v2, it's an object with a code and a message, and there's a new 429 error with a Retry-After header that tells developers how many seconds to wait. Since both changes affect error handling, the guide can cover them in one example:
// v1 if (!res.ok) { const body = await res.json(); console.error(body.error); // "Item not found" } // v2 if (!res.ok) { const { error } = await res.json(); if (error.code === "rate_limited") { const waitSeconds = Number(res.headers.get("Retry-After")); // Wait, then retry the request } console.error(error.message); // "Item not found" } That covers every change from the list in Step 1. You can see the complete Breaking changes section, with every change written out in full, in the finished guide.
Step 4: Add a Migration Checklist
A checklist isn't a standard part of every migration guide, and many good guides don't have one. I prefer to add it in most cases, though, because it helps developers keep track of what they've updated and what's left. After reading through the changes, they can use the checklist to see everything they need to update, so they don't have to scroll back through the guide to find what they missed.
Here's the checklist for the Inventory API guide:
## Migration checklist - [ ] Change the base URL from `/v1` to `/v2` - [ ] Move the API key from the `api_key` query parameter to the `Authorization: Bearer` header - [ ] Replace `page` and `per_page` with `limit` and `cursor` - [ ] Remove code that reads `total_pages` - [ ] Rename `qty` to `quantity` in code that reads responses - [ ] Rename `qty` to `quantity` in adjust request bodies - [ ] Read `error.message` and `error.code` instead of `error` - [ ] Handle `429` errors using the `Retry-After` header - [ ] Test your migration (see below) The - [ ] syntax shows each item as a checkbox, but ticking a box on a docs site doesn't save. So developers can use the list as a reference.
When you write your own checklist, keep these in mind:
- One action per item: Each item is something a developer can do and tick off. "Update pagination" is too vague, so I split it into replacing the parameters and removing the
total_pagescode. - Same order as the guide: The items follow the order of the Breaking changes section, so developers can jump back to the right section if they get stuck.
- Only breaking changes: The new
warehouse_idandreasonfields aren't on the list, because developers don't need to do anything about them. - Testing comes last: The final item points developers to the testing section, so they don't switch to v2 before checking that everything works.
If a migration only has one or two changes, you can skip the checklist, since it would just repeat the guide.
Step 5: Add Testing and Rollback Guidance
Before developers switch to v2 in production, they'll want to be sure their new code works. And if something breaks after they switch, they'll need a way back. This step covers both.
Help developers test their migration
Your testing section should tell developers which parts of their code are most likely to break. For the Inventory API, those are pagination, errors, and rate limits, because they change how developers write their logic and not just a URL or a field name.
Since v1 and v2 both work until the deadline, developers can also run the same request on both versions and compare the results. That's the easiest way to catch something they missed.
This is the testing section from the Inventory API guide:
## Test your migration Before you switch your production code to v2, check that it behaves the same way it did on v1: 1. **Compare the full item list.** Page through all items in v1 and v2 and check that you get the same number of items with the same quantities. 2. **Test the last page.** Make sure your loop stops when `next_cursor` is `null` and doesn't request an extra page. 3. **Test an error.** Request an item ID that doesn't exist and check that your code reads `error.code` (`item_not_found`) and `error.message` correctly. 4. **Test a stock adjustment.** Add or remove stock on a test item with `quantity`, then fetch the item and check that the new value is correct. 5. **Test rate limiting.** If you send requests in bulk, make sure your code waits and retries when it gets a `429`. Every test focuses on one change and shows what a correct result looks like. A vague step like "Test your pagination" doesn't help much, because developers won't know what to look for.
Tell developers how to roll back
Even with good testing, something can still go wrong after developers switch. The rollback section tells them what to do if that happens.
For the Inventory API, rolling back is possible because v1 keeps working until March 31, 2027. The guide tells developers to keep their v1 code until they're confident in v2 and to switch between versions with a setting, so going back doesn't mean rewriting code:
## Roll back v1 keeps working until **March 31, 2027**, so you can switch back if something goes wrong after you migrate. To make rolling back easy, keep your v1 code until you're confident v2 works, and switch between them with a setting, such as an environment variable, instead of editing code. After March 31, 2027, rolling back isn't possible, so finish testing well before that date. Don’t leave out that last sentence. Developers need to know when they can no longer go back to v1, so they have enough time to test before the deadline.
Step 6: Publish and Announce the Guide
When the guide is done, publish it in your docs and let developers know it exists. Don't expect them to find it on their own.
For the Inventory API, I'd share it in these places:
- The docs: Add a banner to the v1 reference pages that links to the guide.
- The changelog: Add an entry for v2 that links to the guide.
- Email: Send it to developers using v1, then send a reminder or two before the deadline.
You can also ask the engineering team to add a Sunset header to v1 responses. It puts the shutdown date in every response, so developers who miss the email still see it.
After the guide is published, keep it up to date. When developers ask the same question in support tickets, add the answer to the guide, and once v1 shuts down, label it as outdated so new developers don't follow it by mistake.
What Are the Most Common Mistakes in API Migration Guides?
A migration guide fails when developers finish reading it and still don't know what to change in their code. Below are five common mistakes that lead to this, and how to avoid them.
- Linking to the changelog instead of explaining: Writing something like "See the changelog for details" forces developers to figure out what each change means for their code. Explain every breaking change in the guide itself.
- Leaving out code examples: Describing a change in words isn't enough. Show the v1 and v2 code side by side, so developers can see what to update.
- Hiding the deadline: If the shutdown date is buried in the middle of the guide, some developers will miss it. Put it in the first paragraph.
- Mixing breaking and non-breaking changes: When new optional features are listed together with breaking changes, it’s hard for developers to tell what’s required and what’s optional. Keep them in separate sections.
- Skipping testing guidance: Without it, developers find problems after they switch to the new version, in production. Tell them what to test and what a correct result looks like.
Conclusion
In this tutorial, you wrote a migration guide for the Inventory API from start to finish. You listed every change between v1 and v2, built the guide around the questions developers ask, documented each change with before-and-after code, and added a checklist, testing steps, and a rollback plan.
You can use the same process for any API you work on. If you’d like something to work from, the finished Inventory API guide and the reference docs are on GitHub and my blog. Copy the structure and swap in your own changes.
If you found this helpful, I share tips on technical writing and documentation on LinkedIn and X. Feel free to connect.

