Migration Guides

In this tutorial, you will learn about Migration Guides. We cover key concepts, practical examples, and best practices to help you master this topic.

Migration guides help developers upgrade from one API version to another by documenting every breaking change with before and after examples, providing step-by-step upgrade instructions, and offering automated migration tools that reduce manual effort and prevent upgrade errors.

What You'll Learn

How to write a migration guide, how to list breaking changes with old and new behavior, how to provide before-and-after code examples, how to create automated migration scripts, and how to handle partial migrations where some endpoints are updated and some are not.

Why It Matters

API upgrades are painful. Developers have existing integrations that work, and changing them risks breaking production systems. A clear migration guide with tested steps and automated tools reduces upgrade friction and keeps developers on supported versions.

Real-World Use

Stripe's API migration guides document every breaking change between versions with before and after examples, a migration checklist, and a compatibility layer for gradual upgrades. DodaTech follows the same pattern for the DodaZIP Compression API v1 to v2 migration.

Migration Guide Structure

flowchart TD
  A[Migration Guide] --> B[Overview]
  A --> C[Breaking Changes List]
  A --> D[Step-by-Step Guide]
  A --> E[Code Migration]
  A --> F[Testing]
  A --> G[Rollback Plan]
  B --> H[Why upgrade]
  B --> I[Timeline]
  B --> J[Support]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Migration Overview

Start with why developers should upgrade and the timeline.

# Migration Guide: v1 to v2

## Overview

Version 2 of the DodaTech Compression API introduces bearer token
authentication, cursor-based pagination, and async job processing.
These changes improve security and support larger file sizes.

### Why Upgrade

- **Security:** v2 uses Bearer tokens instead of API key headers
- **Scale:** v2 supports files up to 1 GB (v1 limit was 100 MB)
- **Reliability:** v2 adds idempotency keys and webhook retries
- **Support:** v1 will be sunset on 2026-10-01

### Migration Timeline

- Now: v2 is available alongside v1
- 2026-07-01: v1 enters maintenance mode (bug fixes only)
- 2026-10-01: v1 is decommissioned (all v1 requests fail)

Breaking Changes List

List every breaking change with old and new behavior.

## Breaking Changes

### 1. Authentication Header Format

| | Before (v1) | After (v2) |
|---|-------------|------------|
| Header | `Authorization: Token abc123` | `Authorization: Bearer abc123` |
| Header format | `Token YOUR_KEY` | `Bearer YOUR_KEY` |

### 2. Pagination Response Format

| | Before (v1) | After (v2) |
|---|-------------|------------|
| Key | `results` | `data` |
| Pagination | `page`, `total` | `pagination.page`, `pagination.total` |

### 3. Compression Endpoint URL

| | Before (v1) | After (v2) |
|---|-------------|------------|
| URL | `POST /v1/compress` | `POST /v2/files/compress` |
| Response | Synchronous | Async with job polling |

## Step-by-Step Migration

Provide sequential upgrade steps that developers can follow.

```markdown
## Step-by-Step Migration

### Step 1: Update Authentication

Replace `Token YOUR_KEY` with `Bearer YOUR_KEY` in all requests.

**cURL (before):**
```bash
curl -H "Authorization: Token YOUR_KEY" https://api.dodatech.com/v1/compress

cURL (after):

curl -H "Authorization: Bearer YOUR_KEY" https://api.dodatech.com/v2/files/compress

Python SDK (before):

client = Client(api_key="YOUR_KEY")

Python SDK (after):

client = Client(api_key="YOUR_KEY")

No code change needed. The SDK handles the header format internally.

Step 2: Update Pagination Parsers

# Before (v1)
results = response["results"]
page = response["page"]
total = response["total"]

# After (v2)
results = response["data"]
page = response["pagination"]["page"]
total = response["pagination"]["total"]

Step 3: Handle Async Compression

# Before (v1) — synchronous
result = requests.post("https://api.dodatech.com/v1/compress", ...)
print(f"Compressed file: {result.json()['download_url']}")

# After (v2) — async with polling
job = client.files.compress(file_url="https://example.com/file.pdf")
job.wait_for_completion()
print(f"Compressed file: {job.download_url}")

## Migration Checklist

Provide a checklist developers can use to track their migration progress.

```markdown
## Migration Checklist

- [ ] Update authentication header from `Token` to `Bearer`
- [ ] Update endpoint URLs from `/v1/` to `/v2/`
- [ ] Update pagination parsers from `results` to `data`
- [ ] Update pagination from flat to nested object
- [ ] Add idempotency keys to critical requests
- [ ] Add async job polling for compression endpoints
- [ ] Update error handling for new error codes
- [ ] Test all updated endpoints in sandbox
- [ ] Deploy to production
- [ ] Monitor for errors after deployment

## Automated Migration Tools

Provide scripts that automate parts of the migration.

```python
# migration_helper.py
import re

def migrate_url(url: str) -> str:
    """Update v1 URLs to v2 format."""
    return url.replace("/v1/", "/v2/")

def migrate_auth_header(header: str) -> str:
    """Update Token format to Bearer format."""
    return re.sub(r"^Token ", "Bearer ", header)

def migrate_response(response: dict) -> dict:
    """Update v1 response format to v2."""
    if "results" in response:
        response["data"] = response.pop("results")
    if "page" in response:
        response.setdefault("pagination", {})["page"] = response.pop("page")
    if "total" in response:
        response.setdefault("pagination", {})["total"] = response.pop("total")
    return response

Common Mistakes

1. No Breaking Changes List

Starting the migration guide without a clear list of breaking changes forces developers to read the entire guide to find what affects them.

2. Before-and-After Without Context

Showing code changes without explaining why the change was made leaves developers unsure about the purpose of the migration.

3. No Timeline

Not providing a sunset date for the old version gives developers no urgency to migrate and no deadline for planning.

4. Assuming Linear Migration

Writing the guide for a single upgrade path when some developers may need to upgrade incrementally through intermediate versions.

5. No Rollback Plan

Not documenting how to revert to the previous version if the migration causes issues in production.

6. Skipping Sandbox Testing

Not instructing developers to test the migration in a sandbox environment before deploying to production.

7. No Validation Steps

Not telling developers how to verify the migration was successful, such as checking specific API responses or running test suites.

Practice Questions

1. What information should every breaking change entry include?

Old behavior, new behavior, the impact on existing code, before-and-after code examples, and a migration action the developer needs to take.

2. Why include a migration timeline?

A timeline with dates for maintenance mode and sunset helps developers plan their upgrade. Without a deadline, migration gets deprioritized indefinitely.

3. What is a migration checklist?

A list of all required changes that developers can check off as they complete each step. It ensures nothing is forgotten during the migration Process.

4. How do automated migration tools help?

Automated scripts handle repetitive migration tasks like URL replacements, header format changes, and response restructuring, reducing manual effort and preventing errors.

5. Challenge: Write a migration guide for an API that has at least 5 breaking changes. Include a breaking changes table, step-by-step instructions with code examples, a migration checklist, and an automated migration script.

FAQ

Mini Project: Write a Migration Guide

Create a migration guide from API v1 to v2 with at least 5 breaking changes. Include an overview with timeline, a breaking changes comparison table, step-by-step instructions with before and after code examples, a migration checklist, and an automated migration script in one language.

What's Next

Migration guides help developers upgrade. Now learn to maintain consistency with an API Style Guide. Then explore API Documentation Tools for tools that automate documentation.