API Platform & Lifecycle · Developer Experience
Changelogs and Change Communication
Tell consumers what changed, what they must do, and when.
Every change should reach consumers in a form they can act on: a changelog (generated from spec diffs, curated with context), migration guides for breaking changes, email/portal notifications to affected consumers (identified from usage data), deprecation headers on affected responses, and SDK warnings. Use consistent categories: Added, Changed, Deprecated, Removed, Fixed, Security.
## 2026-10-08
### Added
- `GET /v1/orders` supports `status` filtering with multiple values (`?status=paid,shipped`).
### Deprecated
- `price` (float) on Order is deprecated in favor of `total` (Money). Sunset: 2027-03-01.
Responses using it now include `Deprecation` and `Sunset` headers. Migration guide: /docs/migrate-money
### Fixed
- `PATCH /v1/orders/{id}` now returns 412 (not 409) on ETag mismatch.
Common pitfalls
- Silent changes discovered by consumers in production.
- Changelogs written for the provider team, not consumers.
- Broadcasting every change to everyone (notify affected consumers).
Key points
- Consumer-oriented changelogs
- Targeted notifications using usage data
- Migration guides for breaking changes
Further reading: Keep a Changelog
Practice questions
How do you know which consumers to notify about a deprecation?
Answer
Use gateway/analytics data on which API keys or client IDs call the affected endpoints or request the affected fields.
What should a migration guide include?
Answer
What's changing and why, the timeline (deprecation and sunset dates), before/after examples, how to test the new behavior, and how to get help.
Open in the app to mark lessons complete, take notes and track your progress.