Skip to main content

API changelog maintained

ab-000368 · api-design.versioning-evolution.changelog
Severity: lowactive

Why it matters

Without an API-specific changelog, consumers upgrading between versions have no way to know which endpoints changed, which fields were added, or which response shapes shifted. A general project changelog that says "various API improvements" is not a substitute. iso-25010:2011 maintainability.modifiability is directly impacted: the cost of each API change is borne by consumers who must diff the implementation themselves rather than reading a curated list of what changed and what they need to update.

Severity rationale

Low because a missing changelog does not cause immediate failure but significantly increases the cost of every consumer upgrade and creates friction for third-party SDK maintainers.

Remediation

Start an API changelog focused exclusively on changes to the API contract. Keep it in API_CHANGELOG.md or a /changelog endpoint, separate from the general project changelog:

# API Changelog

## v1.2.0 - 2026-03-15
### Added
- GET /api/v1/users/:id/preferences
- `timezone` field on User response

### Changed
- GET /api/v1/orders now returns `items` array (was `orderItems`)

### Deprecated
- POST /api/v1/users/search -- use GET /api/v1/users?q= instead

Every entry should include the endpoint affected, what changed, and any migration action required. Date and version-tag every release.

Detection

  • ID: api-design.versioning-evolution.changelog

  • Severity: low

  • What to look for: Check for an API-specific changelog that documents changes to the API contract over time. This could be: a dedicated API_CHANGELOG.md or CHANGELOG.md with API sections, a changelog in the OpenAPI spec description, a /changelog endpoint, or documentation site changelog pages. The changelog should list added endpoints, removed endpoints, changed request/response shapes, and new parameters. It is distinct from a general project changelog -- it specifically covers the API surface.

  • Pass criteria: Count all changelog files and sections found. An API changelog exists with at least 1 entry that documents a change to the API contract (new endpoint, changed field, etc.). Entries include dates and are organized by version or date.

  • Fail criteria: No API changelog exists. Changes to the API are not documented anywhere. Consumers cannot determine what changed between versions or releases.

  • Skip (N/A) when: The API has had exactly one release with no changes since initial deployment. Signal: version 1.0.0 with no evidence of post-launch API changes.

  • Detail on fail: Note what's missing (e.g., "No API changelog. The general CHANGELOG.md exists but does not mention API changes. Consumers upgrading SDK versions have no way to know which endpoints changed."). Max 500 chars.

  • Remediation: Start an API changelog. Keep it focused on the API contract:

    # API Changelog

## v1.2.0 - 2026-03-15
### Added
- GET /api/v1/users/:id/preferences
- `timezone` field on User response

### Changed
- GET /api/v1/orders now returns `items` array (was `orderItems`)

### Deprecated
- POST /api/v1/users/search -- use GET /api/v1/users?q= instead

External references

Taxons

code-quality

History