Change Log
Communicating change is important for any API provider, and having a simple and up-to-date log of what has changed is a great way to make change self-service. Your change log doesn't have to be verbose, but should be accurate and provide as much useful detail for consumers as possible.
Also known as: Changelog, Release Notes, What's New, Updates
Example
Standards
- De facto Keep a Changelog 1.1.0
- De facto Conventional Commits 1.0.0
- SemVer Semantic Versioning 2.0.0
- Schema.org Schema.org releaseNotes
- RSS Advisory Board RSS 2.0
- IETF RFC 4287 — Atom Syndication Format
- OpenAPI Initiative OpenAPI Specification 3.1
HTTP Headers
| Header | Direction | Spec | Description |
|---|---|---|---|
Deprecation |
response | RFC 9745 | Signals that a resource is deprecated, with a timestamp. |
Sunset |
response | RFC 8594 | Signals the date a resource will become unresponsive. |
Link |
response | RFC 8288 | With `rel=sunset` or `rel=deprecation`, points to the changelog entry. |
Media Types
text/markdown— RFC 7763 — CHANGELOG.md is the canonical form.application/rss+xml— Changelog feed for subscribers.application/atom+xml— RFC 4287
OpenAPI Expression
-
info.version(OpenAPI 3.x) — SemVer string of the API description; the anchor entries are tied to. -
deprecated(OpenAPI 3.x) — Operation- or parameter-level deprecation flag referenced from changelog entries. -
info.x-api-lifecycle(Common vendor extension) — Lifecycle stage (alpha/beta/stable/deprecated) — frequently surfaced in the changelog.
Link Relations
alternate— HTML / RFC 8288sunset— RFC 8594deprecation— RFC 9745
Governance Rules
info-version(Spectral built-in) — `info.version` must be set so changelog entries can be anchored to a release.oas-version-bump-on-breaking(House rule) — Breaking changes must bump the major version (SemVer) and produce a changelog entry.deprecated-operations-changelog(House rule) — Operations flagged `deprecated: true` must have a corresponding changelog entry and Sunset/Deprecation headers.
Risk & Compliance
Compliance:
- Contract / SLA — material API changes often require advance notice
- Privacy regulations (GDPR Art. 13/14) — material changes to data handling require user notification
Security: Changelogs that disclose CVE-adjacent fixes before coordinated release can expose unpatched consumers; pair security-relevant entries with advisory channels. Conversely, silent breaking changes undermine trust and can trigger outage post-mortems against the provider.
Tools
- semantic-release — Release automation (MIT)
- Conventional Changelog — Changelog generator (ISC)
- release-please — Release automation (Apache-2.0)
- Bump.sh — API diff and changelog
- oasdiff — OpenAPI diff (Apache-2.0)
- Optic — API diff and governance
Suggested Metrics
releases_per_quarter— Number of versioned releases captured in the changelog.breaking_changes_per_release— Count of entries flagged as breaking in each release.deprecation_lead_time_days— Days between a deprecation entry and the corresponding sunset.changelog_freshness_days— Days between the latest API change and its changelog entry.
Example Implementations
- Stripe — Dated API versions paired with prose upgrade guides per change.
- GitHub — Platform-wide changelog with RSS feed and category filters.
- Twilio — Per-product changelog feeds aligned with SDK release notes.
- Shopify — Quarterly API versions with detailed release notes per version.
Related Properties
Tags
- Change Log
- Versioning
- Communication