Documenting Breaking Changes — Complete Guide

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

Breaking changes require careful documentation to help developers update their integrations without production outages by identifying what changed, communicating clear deprecation timelines, providing before and after examples, and offering Migration guides that minimize disruption.

What You'll Learn

What constitutes a breaking change, how to identify breaking changes in APIs, how to communicate breaking changes effectively, how to write before-and-after migration examples, how to document deprecation timelines, and how to provide automated migration tools.

Why It Matters

Breaking changes are the most disruptive event for API consumers. An unannounced breaking change can cause production outages across all integrations. Clear, early communication with detailed migration guidance maintains trust and minimizes support incidents.

Real-World Use

Stripe announces breaking changes at least 90 days before they take effect. Each breaking change has a dedicated migration guide with before and after code examples, a changelog entry, and email notifications to API key owners. DodaTech follows the same 90-day deprecation policy.

Breaking Change Categories

flowchart TD
  A[Breaking Changes] --> B[Request Changes]
  A --> C[Response Changes]
  A --> D[Behavior Changes]
  A --> E[Removal]
  B --> F[Required parameters added]
  B --> G[Parameter type changed]
  C --> H[Field removed or renamed]
  C --> I[Response format changed]
  D --> J[Rate limits decreased]
  D --> K[SLA changed]
  E --> L[Endpoint removed]
  E --> M[Feature removed]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

What Counts as a Breaking Change

Document and communicate every change in these categories.

## Breaking Changes

Any change that could cause existing integrations to fail is a breaking
change. Examples include:

### Request Changes
- Adding a required parameter to an existing endpoint
- Changing a parameter type (string to integer)
- Changing parameter validation rules
- Changing authentication format or requirements

### Response Changes
- Removing or renaming a response field
- Changing a response field type
- Changing error response format
- Adding new required fields to webhook payloads

### Behavior Changes
- Changing processing from sync to async
- Decreasing rate limits
- Changing pagination method
- Changing default parameter values

### Removals
- Deprecating and removing an endpoint
- Deprecating and removing a parameter
- Removing an SDK method

## Communicating Breaking Changes

Use multiple channels to ensure developers see the announcement.

```markdown
## Breaking Change Announcement Template

### Subject: Upcoming Breaking Change — Authentication Header Format

**What's changing:** The authentication header format is changing from
`Authorization: Token YOUR_KEY` to `Authorization: Bearer YOUR_KEY`.

**When:** This change takes effect on 2026-10-01 (90 days from today).

**Why:** Bearer token format is the industry standard and improves
security by supporting JWT-based authentication in future releases.

**What you need to do:** Update all API requests to use the Bearer
scheme. Your API keys remain the same.

**Migration guide:** [/docs/migration-auth-format](/docs/migration-auth-format)

**Before:**

Authorization: Token abc123def456

**After:**

Authorization: Bearer abc123def456

**Questions?** Contact api-support@dodatech.com

## Migration Guide for Breaking Changes

Every breaking change needs a migration guide with before and after examples.

```markdown
## Migration Guide: Authentication Header Format

### Overview
The Authorization header format is changing from Token to Bearer.
Your API key value stays the same. Only the prefix changes.

### Updates Required

**cURL:**
```bash
# Before
curl -H "Authorization: Token YOUR_KEY" https://api.dodatech.com/v2/files

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

Python (using requests):

# Before
headers = {"Authorization": f"Token {api_key}"}

# After
headers = {"Authorization": f"Bearer {api_key}"}

Python SDK: No changes needed. The SDK handles the format internally.

Rollout Timeline

• Now: Both Token and Bearer formats accepted
• 2026-09-01: Token format triggers a deprecation warning header
• 2026-10-01: Token format returns 401 Unauthorized

Providing a Transition Period

Run old and new behavior in parallel during the transition.

## Transition Period

During the transition period, both old and new formats are accepted:

| Date Range | Old Format | New Format | Response |
|-----------|------------|------------|----------|
| Now - 2026-08-31 | Accepted | Accepted | No warning |
| 2026-09-01 - 2026-09-30 | Accepted | Accepted | Warning header |
| 2026-10-01+ | Rejected | Accepted | 401 error |

The warning header during the transition period:

Warning: 299 - "Authorization: Token format is deprecated. Use 'Authorization: Bearer YOUR_KEY' instead. Sunset: 2026-10-01"

Common Mistakes

1. Not Announcing Breaking Changes

Making breaking changes without any announcement causes production outages and erodes developer trust permanently.

2. Insufficient Notice Period

Announcing breaking changes with less than 30 days notice. Industry standard is 90 days minimum for major breaking changes.

3. No Migration Examples

Announcing a change without showing developers exactly what to update. Every breaking change needs before and after code examples.

4. Assuming Developers Read Changelogs

Relying solely on the changelog to communicate breaking changes. Use multiple channels: email, blog post, dashboard notification, and API warning headers.

5. No Transition Period

Switching from old to new behavior instantly without a transition period. Run both formats in parallel to allow gradual migration.

6. Not Classifying Breaking Changes

Calling a breaking change a minor improvement. Be honest about the impact. Developers prefer clear communication over sugarcoating.

7. No Rollback Plan

Not documenting how to revert if the migration causes issues. Provide clear rollback instructions for each breaking change.

Practice Questions

1. What are the four categories of breaking changes?

Request changes (required parameters, type changes), response changes (field removal, format changes), behavior changes (sync to async, rate limit changes), and removals (endpoints, parameters, features).

2. How long should the deprecation period be for breaking changes?

90 days minimum is the industry standard. This gives developers time to plan, test, and deploy updates without rushing.

3. What communication channels should be used for breaking changes?

Changelog, email notification to API key owners, dashboard banner, API warning headers, blog post, and migration guide documentation.

4. What is a transition period and why is it important?

A transition period runs old and new behavior in parallel. It allows developers to migrate gradually, testing their updates against the new behavior while the old behavior still works as a fallback.

5. Challenge: Write a breaking change announcement for an API change that includes before and after code examples, a transition period timeline, a migration checklist, and rollback instructions.

FAQ

Mini Project: Breaking Change Communication

Create a complete breaking change communication package for an API. Include the changelog entry, email announcement, migration guide with before and after examples for 3 languages, transition timeline, migration checklist, automated migration script, and rollback instructions.

What's Next

Breaking changes are inevitable but manageable. Now apply everything you have learned in the API Documentation Project where you create a complete API documentation set from scratch.