Learn to write API changelogs: version entries, breaking change announcements, deprecation notices, and migration guides.
0 / 5 completed
1 / 5
What is a 'breaking change' announcement in an API changelog?
Breaking change announcement: 'BREAKING in v3.0: The user_id field is renamed to userId in all responses. Clients using user_id must update to userId by [date]. Migration: replace all user_id references with userId in your API response parsing code. v2.x API remains available until [sunset date].'
2 / 5
What is semantic versioning (semver) in API versioning vocabulary?
Semver for APIs: v1.0.0 → v1.1.0 (new optional field added, backward compatible) → v1.1.1 (bug fix in existing endpoint) → v2.0.0 (removed deprecated field, breaking change). Clients can safely upgrade to 1.x minor/patch versions; major version upgrades require migration planning. Semantic versioning makes version management communicable.
3 / 5
What is a 'deprecation notice' in an API changelog?
Deprecation notice: 'DEPRECATED: The GET /users/search endpoint is deprecated as of v2.3.0 and will be removed in v3.0.0 (planned Q4 2025). Migration: use GET /users?q= instead, which provides the same functionality with better performance. The deprecated endpoint will continue working until v3.0.0 release.'
4 / 5
What is 'sunset date' in API versioning vocabulary?
Sunset date: the hard deadline for removal. 'The v1 API has a sunset date of December 31, 2025. After this date, all v1 API requests will return 410 Gone.' A well-communicated sunset: announced far in advance (typically 6-12 months for widely-used APIs), includes migration guides, and uses the Sunset HTTP header in responses from deprecated endpoints.
5 / 5
What is 'additive change' vs. 'breaking change' in API evolution vocabulary?
Additive changes (safe): adding a new optional response field, adding a new endpoint, adding new enum values (with caution), relaxing validation constraints. Breaking changes: removing a field, renaming a field, changing a field type, making an optional field required, removing an endpoint, changing the HTTP method of an endpoint. The Robustness Principle: be conservative in what you send, liberal in what you accept.