API Changelog Writing | API Design Language Exercises

1 / 5

Which changelog entry correctly follows the Keep a Changelog standard for a newly added endpoint?

Option D correctly follows the Keep a Changelog format. This standard is widely adopted for APIs because it creates machine-parseable, developer-friendly change history.

Required element	Format	In Option D
Version header	`## [X.Y.Z] — YYYY-MM-DD`	`## [2.3.0] — 2025-03-15`
Category heading	`### Added / Changed / Deprecated / Removed / Fixed / Security`	`### Added`
Bullet entry	Active voice, specific, with context	- `POST /payments/refund`: Initiates a refund…
Technical specifics	What fields, what it returns, what it does	Required fields, return object described

The six Keep a Changelog categories:

Added — new features, new endpoints, new fields
Changed — changes to existing functionality
Deprecated — soon-to-be removed features (give timeline)
Removed — removed features (previously deprecated)
Fixed — bug fixes
Security — fixes to security vulnerabilities

2 / 5

A bug caused the total_amount response field in GET /orders/{id} to return values in cents (e.g. 1999) instead of dollars (e.g. 19.99) for the past three months. This has now been corrected.

Under which Keep a Changelog category should this correction be documented?

Option C is correct. The key distinction is intent: was the previous behaviour the designed behaviour (then a "Changed" entry documents the intentional departure) or a defect (then "Fixed" is correct)?

Category	Use when	Example
Fixed	The previous behaviour was a bug — not what was designed or documented	`total_amount` returning cents instead of dollars (spec always said dollars)
Changed	The previous behaviour was intentional and is now intentionally different	Changing `total_amount` to return cents as a deliberate design decision (breaking change — needs version bump)

Important nuance: A "Fixed" entry that corrects existing behaviour can still be a breaking change in practice — consumers may have written code that worked around the bug. The example here (returning cents when dollars were documented) likely means some consumers are already dividing by 100 as a workaround. A well-written Fixed entry acknowledges this: "Fixed: total_amount now returns dollar values as documented. Note: if your integration divides this value by 100 as a workaround, that workaround should be removed."

3 / 5

Which changelog entry most clearly communicates a breaking change to developers scanning the changelog?

Option A contains every element required for a breaking change entry that developers can act on. Entries B, C, and D fail in specific ways:

Entry	What's missing
B — "v3.0 is now live!"	No breaking change label; sounds like a minor enhancement; no action guidance
C — "Updated to v3"	Under "Changed" not "Removed"; no specifics; no migration path; no urgency
D — "has been modernised"	Vague marketing language; no technical specifics; no date; no action required

What makes Option A work:

## [3.0.0] — major version increment signals breaking change in SemVer
### Removed — correct category; the endpoint is gone, not changed
BREAKING — explicit keyword for engineers scanning changelogs
Old endpoint named + new endpoint named — reduces ambiguity
Field migration explained — category_ids replaces category_id
Deadline — "before 2025-06-01" creates urgency for sprint planning
Migration guide linked — detailed instructions one click away

4 / 5

Which writing style is standard for individual Keep a Changelog bullet entries?

Option B is the standard style: active voice, imperative/past tense action verb at the start, specific change described, no filler words.

Style issue	Options A, C, D	Option B
Voice	Passive ("were updated", "was decided")	Active ("Updated")
Agent mention	"by the engineering team", "we are happy" — unnecessary	No agent — the change is the subject
Filler phrases	"we are happy to announce", "it was decided"	None — goes straight to the change
Specificity	A is specific; C and D are vague about what ETag support means	Specific: what changed (cache headers + ETag) and why it matters (conditional GET)

Changelog entry formula: [Action verb] [what changed] [why or what it enables] [if needed: affected versions/endpoints]

Examples of well-formatted entries:

✓ "Added cursor field to all paginated list responses for cursor-based pagination."
✓ "Fixed race condition in POST /transactions that could cause duplicate charges on network timeout."
✓ "Deprecated GET /v2/customers. Use GET /v3/customers. Sunset date: 2026-01-01."

5 / 5

A changelog shows these entries in reverse chronological order: v2.1.3 (today), v2.1.2, v2.1.1, v2.0.0 — with no v2.1.0 entry anywhere in the file.

What does the absence of a v2.1.0 entry most likely signal?

Option D describes the most common and technically accurate explanation for a missing version in an otherwise sequential changelog. The [YANKED] tag is the Keep a Changelog convention for this situation:

Keep a Changelog convention	Usage
`[YANKED]` tag	Added to a version entry to signal it was pulled from distribution. Example: `## [2.1.0] — 2025-03-01 [YANKED]`
Why document yanked versions?	Preserves audit trail; explains the gap in the version sequence; helps users who managed to install the yanked version understand they need to upgrade

Reading a changelog as a senior engineer:

A jump from v2.0.0 directly to v2.1.1 is a yellow flag — worth noting when evaluating a dependency
A major version jump (v1.x → v2.0.0) always means breaking changes and should prompt a review of the migration guide
Many minor patch versions in rapid succession (v2.1.1, v2.1.2, v2.1.3 within a week) may indicate instability in a release area
Long gaps between versions are common for stable, well-designed APIs — they indicate the API contract is settled