API Changelog Template

Overview

API consumers need to know what changed, when it changed, and whether they need to act. An unstructured changelog — or no changelog at all — forces consumers to diff your API or discover breaking changes in production. This template provides a standardized format for documenting every API change with version, date, severity, and migration guidance.

When to Use

Use this resource when:

• Releasing a new API version or feature
• Deprecating or removing an endpoint or field
• Fixing a bug that affects API behavior
• Publishing a monthly or quarterly API update

Solution

# API Changelog

## 2.5.0 — 2026-06-26

### Breaking Changes
- **Removed:** `GET /v1/orders/{id}/items` — Use `GET /v2/orders/{id}?expand=items` instead
- **Changed:** `total` field renamed to `totalAmount` in all order responses
- **Required:** `X-Request-ID` header now mandatory for all write operations

### New Features
- **Added:** `POST /v2/orders/bulk` — Create up to 100 orders in a single request
- **Added:** `paymentStatus` field to order responses (`pending`, `paid`, `failed`)
- **Added:** Webhook event `order.payment_failed` for failed payment notifications

### Fixes
- **Fixed:** `GET /v2/products` now returns empty array `[]` instead of `null` when no products exist
- **Fixed:** Date fields now consistently return ISO 8601 format with timezone offset

### Deprecations
- **Deprecated:** `customer_id` query parameter — Use `customerId` instead (sunset: 2026-10-01)
- **Deprecated:** `v1` API base path — Migrate to `v2` before 2026-12-01

## 2.4.0 — 2026-05-15

### New Features
- **Added:** `PATCH /v2/orders/{id}` for partial order updates
- **Added:** Rate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`) to all responses

### Fixes
- **Fixed:** `500 Internal Server Error` on `POST /v2/orders` when `items` array was empty

---

## Versioning Policy

We follow [Semantic Versioning](https://semver.org/):
- **MAJOR:** Breaking changes that require consumer action
- **MINOR:** New features, backward compatible
- **PATCH:** Bug fixes, backward compatible

## Change Categories

| Category | Description | Consumer Action Required |
|----------|-------------|--------------------------|
| Breaking Change | Existing integrations may fail | Yes — migration required |
| New Feature | New endpoints, fields, or behaviors | Optional — adopt when ready |
| Fix | Corrected bug or inconsistent behavior | No — but verify if you relied on old behavior |
| Deprecation | Feature scheduled for removal | Yes — before sunset date |

## Subscribe to Changes

- **RSS Feed:** https://developer.example.com/changelog.xml
- **Email:** Subscribe at https://developer.example.com/subscribe
- **Webhook:** Configure `api.changelog_published` event in your dashboard
- **Slack:** Join #api-announcements on our community Slack

Explanation

The changelog uses a version-date-entry hierarchy so consumers can scan for their current version and see everything that changed since. Breaking changes are listed first because they demand immediate attention. Each entry includes a verb (Added, Removed, Fixed, Deprecated) so consumers understand the nature of the change at a glance. The versioning policy section reduces confusion about what each version number means.

Variants

Context	Approach	Notes
Public API	Full changelog with RSS/email	Consumers self-serve, reduces support tickets
Internal API	Slack + short summary	Faster, less ceremony
Partner API	Email + migration guide link	Partners need white-glove communication

Best Practices

1. Publish the changelog before deploying the change — not after consumers report issues
2. Group entries by severity — breaking changes first, then features, then fixes
3. Include migration instructions with every breaking change, not just a description
4. Link to documentation for complex new features instead of explaining in the changelog
5. Archive old versions but keep them accessible — enterprise clients may be several versions behind

Common Mistakes

1. Mixing bug fixes and breaking changes without clear categorization
2. Writing “various bug fixes” instead of listing specific fixes consumers care about
3. Publishing changelogs days after the deployment — consumers are already broken
4. Not versioning the changelog itself — if the changelog changes, consumers lose trust
5. Forgetting to document removed fields — consumers discover missing data only in production

Frequently Asked Questions

How far back should the changelog go?

Keep at least the last 12 months of changes online. Archive older versions in a separate page. Enterprise clients with long procurement cycles may need to reference changes from a year ago.

Should I document internal-only changes?

No. The changelog is for consumers. Internal refactoring, CI/CD changes, or infrastructure updates belong in internal release notes, not the public API changelog.

What if a bug fix changes behavior that some consumers relied on?

Document it as a breaking change if the old behavior was documented. If the old behavior was a bug, document it as a fix but include a note: “Previous behavior was unintentional and inconsistent with documentation.”