principletypescriptModerate

API Changelog: Maintain a machine-readable and human-readable changelog

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

changelogversioningbreaking-changerelease-notessemverdocumentation

Problem

API consumers cannot safely upgrade when changelog entries are absent, vague, or only in prose. They cannot automate dependency management without structured change data.

Solution

Maintain a CHANGELOG.md following Keep a Changelog conventions for human readers. Additionally expose a /changelog endpoint returning structured JSON with version, date, type (breaking/feature/fix/deprecation), and description. Reference the changelog in error responses for breaking changes.

Why

A structured changelog is the primary trust-building tool between API producers and consumers. It allows automated tooling to detect breaking changes and generate upgrade guides.

Gotchas

Mark every change as breaking or non-breaking explicitly — ambiguity erodes trust.
Include the API version in every changelog entry, not just implicit ordering.
Link to migration guides for every breaking change entry.

Code Snippets

Structured changelog endpoint schema

interface ChangelogEntry {
  version: string
  date: string // ISO 8601
  changes: Array<{
    type: 'breaking' | 'feature' | 'fix' | 'deprecation'
    description: string
    migrationGuide?: string
  }>
}

// GET /changelog
app.get('/changelog', (_, res) => {
  res.json(changelog satisfies ChangelogEntry[])
})

Revisions (0)

No revisions yet.