API Changelog — Why Breaking Changes Must Be Documented

Why API changelogs are critical

When you change an API, you change your developers' code. Undocumented breaking changes erode trust faster than any other mistake. An API changelog is your contract with your developers.

What counts as a breaking change?

A breaking change is any modification that requires existing consumers to update their code:

• Removing an endpoint or field
• Renaming a field or changing its structure
• Changing a field type (string to integer)
• Changing behavior (different default values, new required fields)
• Changing authentication requirements

How to document API changes

The best API changelogs include the change, the reason, and a migration path:

## API v2.0.0 — Breaking Changes

### Removed
- `GET /api/v1/entries` → Use `GET /api/v2/entries`
- `X-Api-Key` header → Use `Authorization: Bearer dpl_...`

### Changed
- Response envelope: `{"entries": [...]}` → `{"data": [...], "meta": {...}}`
- Date format: `YYYY-MM-DD` → ISO 8601 `2026-04-02T12:00:00Z`

### Migration Guide
1. Update your base URL from `/api/v1` to `/api/v2`
2. Replace `X-Api-Key` with `Authorization: Bearer` header
3. Update response parsing for new envelope format

API versioning strategies

• URL path versioning — /api/v1/, /api/v2/
• Header versioning — Accept: application/vnd.deplyd.v2+json
• Query parameter — ?version=2

Best practices

1. Deprecate before you remove. Give developers at least 3 months notice.
2. Set a sunset date and communicate it clearly in your changelog.
3. Provide a migration guide for every breaking change.
4. Notify API consumers via email and changelog when breaking changes are coming.
5. Run old and new versions in parallel during the transition period.