# API changelog maintained

- **Pattern:** `ab-000368` (`api-design.versioning-evolution.changelog`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000368
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000368)

## 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:

```markdown
# 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:** `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:

  ```markdown
  # 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

- iso-25010 maintainability.modifiability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-000368