📝 API Changelog Writing
Master the Keep a Changelog standard: entry categories, breaking change language, active voice style, and reading version sequences. Intermediate
0 / 26 completed
1 / 26
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 / 26
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 / 26
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_idsreplacescategory_id - Deadline — "before 2025-06-01" creates urgency for sprint planning
- Migration guide linked — detailed instructions one click away
4 / 26
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
cursorfield to all paginated list responses for cursor-based pagination." - ✓ "Fixed race condition in
POST /transactionsthat could cause duplicate charges on network timeout." - ✓ "Deprecated
GET /v2/customers. UseGET /v3/customers. Sunset date: 2026-01-01."
5 / 26
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
6 / 26
Sarah from the backend team posted this message in Slack after reviewing a pull request that added a new user authentication endpoint:
"Okay, I've reviewed the changes to /auth/register. The PR includes a new field, user_metadata, which allows users to store custom data. I'm happy with this addition. Just a note: we should definitely update the API documentation to reflect this change."This scenario highlights the importance of proactive communication in a code review. While documentation updates are often necessary after new features are added, Sarah's message effectively communicates that a change has been made (the addition of `user_metadata`) and suggests a relevant action – updating the API documentation. The other options misrepresent Sarah's role or fail to acknowledge the need for clear communication about API updates.
7 / 26
PR Description
During a code review for a new payment processing endpoint, David writes the following description for his pull request:
"Added support for accepting payments via Stripe. This includes a new `stripe_secret_key` parameter in the `/payments` route and updates to the webhook handling logic. We've also added some logging around successful and failed transactions."The correct option highlights that the description is clear and concise. A good PR description should quickly convey the purpose of the change, including new parameters, logic updates, and any relevant considerations like rate limits or potential breaking changes. The other options present misconceptions: simply stating 'it's clear' doesn't assess the quality; lacking detail is insufficient; and failing to address breaking changes or rate limits would be poor practice. David's description strikes a good balance between brevity and essential information.
8 / 26
Mark is working on updating the API changelog for a new feature: a real-time chat endpoint. He's noticed that several recent entries are too verbose and lack specific details about *why* the change was made. During a code review discussion, his teammate, Emily, suggests he should focus on clarity and impact. Which of the following statements best reflects Mark's responsibility when writing API changelog entries according to Keep a Changelog principles?
Keep a Changelog emphasizes communicating the *why* behind changes. While listing technical details is important, the core principle is to explain the problem being addressed and the value provided by the change. Option A incorrectly suggests simply listing everything; option B ignores the core purpose of Keep a Changelog. Option D misinterprets the guidelines, prioritizing format over clarity. The correct answer focuses on articulating the reason for the change – this aligns with the principles of transparency and understanding.
9 / 26
David is reviewing a pull request for a new payment processing endpoint. He's noticed the changelog entry for the addition of Stripe support is quite detailed, listing all the changes – the `stripe_secret_key` parameter, webhook updates, and logging. However, his teammate, Emily, points out that the changelog should focus on the *impact* of the change rather than simply describing what was added. Which of the following best reflects David's responsibility according to Keep a Changelog principles in this situation?Option A: The changelog entry is perfectly acceptable as it provides a comprehensive overview of all technical changes.
Option B: David should remove the details about the webhook updates and logging, focusing solely on adding the `stripe_secret_key` parameter to keep the changelog concise.
Option C: David should rewrite the changelog entry to clearly state how this change improves payment processing, highlighting the benefits for users and developers.
Option D: David should add a separate section to the changelog detailing the technical implementation details of the Stripe integration, regardless of its relevance to consumers.
The core principle of Keep a Changelog is to focus on the *impact* of changes rather than simply listing what was added or modified. Option C aligns with this by emphasizing communicating the benefits and how the change improves functionality. Options A and B incorrectly suggest detailed technical descriptions are always necessary, while option D deviates from the standard by creating an unstructured section. This demonstrates understanding that changelogs should be easily digestible for developers who need to quickly understand the implications of a new API version.
10 / 26
Sarah from the backend team posted this message in Slack after reviewing a pull request that added a new user authentication endpoint:
"Okay, I've reviewed the changes to /auth/register. The PR includes a new field, user_metadata, which allows users to store custom data. I'm happy with this addition. Just a note: we should definitely update the API documentation to reflect this change."This scenario highlights the importance of proactive communication in a code review. While documentation updates are often necessary after new features are added, Sarah's message effectively communicates that a change has been made (the addition of `user_metadata`) and suggests a relevant action – updating the API documentation. The other options misrepresent Sarah's role or fail to acknowledge the need for clear communication about API updates.
11 / 26
PR Description
During a code review for a new payment processing endpoint, David writes the following description for his pull request:
"Added support for accepting payments via Stripe. This includes a new `stripe_secret_key` parameter in the `/payments` route and updates to the webhook handling logic. We've also added some logging around successful and failed transactions."The correct option highlights that the description is clear and concise. A good PR description should quickly convey the purpose of the change, including new parameters, logic updates, and any relevant considerations like rate limits or potential breaking changes. The other options present misconceptions: simply stating 'it's clear' doesn't assess the quality; lacking detail is insufficient; and failing to address breaking changes or rate limits would be poor practice. David's description strikes a good balance between brevity and essential information.
12 / 26
Mark is working on updating the API changelog for a new feature: a real-time chat endpoint. He's noticed that several recent entries are too verbose and lack specific details about *why* the change was made. During a code review discussion, his teammate, Emily, suggests he should focus on clarity and impact. Which of the following statements best reflects Mark's responsibility when writing API changelog entries according to Keep a Changelog principles?
Keep a Changelog emphasizes communicating the *why* behind changes. While listing technical details is important, the core principle is to explain the problem being addressed and the value provided by the change. Option A incorrectly suggests simply listing everything; option B ignores the core purpose of Keep a Changelog. Option D misinterprets the guidelines, prioritizing format over clarity. The correct answer focuses on articulating the reason for the change – this aligns with the principles of transparency and understanding.
13 / 26
David is reviewing a pull request for a new payment processing endpoint. He's noticed the changelog entry for the addition of Stripe support is quite detailed, listing all the changes – the `stripe_secret_key` parameter, webhook updates, and logging. However, his teammate, Emily, points out that the changelog should focus on the *impact* of the change rather than simply describing what was added. Which of the following best reflects David's responsibility according to Keep a Changelog principles in this situation?Option A: The changelog entry is perfectly acceptable as it provides a comprehensive overview of all technical changes.
Option B: David should remove the details about the webhook updates and logging, focusing solely on adding the `stripe_secret_key` parameter to keep the changelog concise.
Option C: David should rewrite the changelog entry to clearly state how this change improves payment processing, highlighting the benefits for users and developers.
Option D: David should add a separate section to the changelog detailing the technical implementation details of the Stripe integration, regardless of its relevance to consumers.
The core principle of Keep a Changelog is to focus on the *impact* of changes rather than simply listing what was added or modified. Option C aligns with this by emphasizing communicating the benefits and how the change improves functionality. Options A and B incorrectly suggest detailed technical descriptions are always necessary, while option D deviates from the standard by creating an unstructured section. This demonstrates understanding that changelogs should be easily digestible for developers who need to quickly understand the implications of a new API version.
14 / 26
Sarah from the backend team posted this message in Slack after reviewing a pull request that added a new user authentication endpoint:
"Okay, I've reviewed the changes to /auth/register. The PR includes a new field, user_metadata, which allows users to store custom data. I'm happy with this addition. Just a note: we should definitely update the API documentation to reflect this change."This scenario highlights the importance of proactive communication in a code review. While documentation updates are often necessary after new features are added, Sarah's message effectively communicates that a change has been made (the addition of `user_metadata`) and suggests a relevant action – updating the API documentation. The other options misrepresent Sarah's role or fail to acknowledge the need for clear communication about API updates.
15 / 26
PR Description
During a code review for a new payment processing endpoint, David writes the following description for his pull request:
"Added support for accepting payments via Stripe. This includes a new `stripe_secret_key` parameter in the `/payments` route and updates to the webhook handling logic. We've also added some logging around successful and failed transactions."The correct option highlights that the description is clear and concise. A good PR description should quickly convey the purpose of the change, including new parameters, logic updates, and any relevant considerations like rate limits or potential breaking changes. The other options present misconceptions: simply stating 'it's clear' doesn't assess the quality; lacking detail is insufficient; and failing to address breaking changes or rate limits would be poor practice. David's description strikes a good balance between brevity and essential information.
16 / 26
Mark is working on updating the API changelog for a new feature: a real-time chat endpoint. He's noticed that several recent entries are too verbose and lack specific details about *why* the change was made. During a code review discussion, his teammate, Emily, suggests he should focus on clarity and impact. Which of the following statements best reflects Mark's responsibility when writing API changelog entries according to Keep a Changelog principles?
Keep a Changelog emphasizes communicating the *why* behind changes. While listing technical details is important, the core principle is to explain the problem being addressed and the value provided by the change. Option A incorrectly suggests simply listing everything; option B ignores the core purpose of Keep a Changelog. Option D misinterprets the guidelines, prioritizing format over clarity. The correct answer focuses on articulating the reason for the change – this aligns with the principles of transparency and understanding.
17 / 26
David is reviewing a pull request for a new payment processing endpoint. He's noticed the changelog entry for the addition of Stripe support is quite detailed, listing all the changes – the `stripe_secret_key` parameter, webhook updates, and logging. However, his teammate, Emily, points out that the changelog should focus on the *impact* of the change rather than simply describing what was added. Which of the following best reflects David's responsibility according to Keep a Changelog principles in this situation?Option A: The changelog entry is perfectly acceptable as it provides a comprehensive overview of all technical changes.
Option B: David should remove the details about the webhook updates and logging, focusing solely on adding the `stripe_secret_key` parameter to keep the changelog concise.
Option C: David should rewrite the changelog entry to clearly state how this change improves payment processing, highlighting the benefits for users and developers.
Option D: David should add a separate section to the changelog detailing the technical implementation details of the Stripe integration, regardless of its relevance to consumers.
The core principle of Keep a Changelog is to focus on the *impact* of changes rather than simply listing what was added or modified. Option C aligns with this by emphasizing communicating the benefits and how the change improves functionality. Options A and B incorrectly suggest detailed technical descriptions are always necessary, while option D deviates from the standard by creating an unstructured section. This demonstrates understanding that changelogs should be easily digestible for developers who need to quickly understand the implications of a new API version.
18 / 26
Sarah from the backend team posted this message in Slack after reviewing a pull request that added a new user authentication endpoint:
"Okay, I've reviewed the changes to /auth/register. The PR includes a new field, user_metadata, which allows users to store custom data. I'm happy with this addition. Just a note: we should definitely update the API documentation to reflect this change."This scenario highlights the importance of proactive communication in a code review. While documentation updates are often necessary after new features are added, Sarah's message effectively communicates that a change has been made (the addition of `user_metadata`) and suggests a relevant action – updating the API documentation. The other options misrepresent Sarah's role or fail to acknowledge the need for clear communication about API updates.
19 / 26
PR Description
During a code review for a new payment processing endpoint, David writes the following description for his pull request:
"Added support for accepting payments via Stripe. This includes a new `stripe_secret_key` parameter in the `/payments` route and updates to the webhook handling logic. We've also added some logging around successful and failed transactions."The correct option highlights that the description is clear and concise. A good PR description should quickly convey the purpose of the change, including new parameters, logic updates, and any relevant considerations like rate limits or potential breaking changes. The other options present misconceptions: simply stating 'it's clear' doesn't assess the quality; lacking detail is insufficient; and failing to address breaking changes or rate limits would be poor practice. David's description strikes a good balance between brevity and essential information.
20 / 26
Mark is working on updating the API changelog for a new feature: a real-time chat endpoint. He's noticed that several recent entries are too verbose and lack specific details about *why* the change was made. During a code review discussion, his teammate, Emily, suggests he should focus on clarity and impact. Which of the following statements best reflects Mark's responsibility when writing API changelog entries according to Keep a Changelog principles?
Keep a Changelog emphasizes communicating the *why* behind changes. While listing technical details is important, the core principle is to explain the problem being addressed and the value provided by the change. Option A incorrectly suggests simply listing everything; option B ignores the core purpose of Keep a Changelog. Option D misinterprets the guidelines, prioritizing format over clarity. The correct answer focuses on articulating the reason for the change – this aligns with the principles of transparency and understanding.
21 / 26
David is reviewing a pull request for a new payment processing endpoint. He's noticed the changelog entry for the addition of Stripe support is quite detailed, listing all the changes – the `stripe_secret_key` parameter, webhook updates, and logging. However, his teammate, Emily, points out that the changelog should focus on the *impact* of the change rather than simply describing what was added. Which of the following best reflects David's responsibility according to Keep a Changelog principles in this situation?Option A: The changelog entry is perfectly acceptable as it provides a comprehensive overview of all technical changes.
Option B: David should remove the details about the webhook updates and logging, focusing solely on adding the `stripe_secret_key` parameter to keep the changelog concise.
Option C: David should rewrite the changelog entry to clearly state how this change improves payment processing, highlighting the benefits for users and developers.
Option D: David should add a separate section to the changelog detailing the technical implementation details of the Stripe integration, regardless of its relevance to consumers.
The core principle of Keep a Changelog is to focus on the *impact* of changes rather than simply listing what was added or modified. Option C aligns with this by emphasizing communicating the benefits and how the change improves functionality. Options A and B incorrectly suggest detailed technical descriptions are always necessary, while option D deviates from the standard by creating an unstructured section. This demonstrates understanding that changelogs should be easily digestible for developers who need to quickly understand the implications of a new API version.
22 / 26
During a code review of a new API endpoint for user profiles, Emily notices that the changelog entry states: 'Updated user profile data structure. Introduced
new_field.' She believes this is insufficient. What should Emily suggest to improve the clarity of the changelog?This scenario focuses on providing context. The changelog entry needs to explain *why*
new_field was added – for example, 'to support new reporting requirements' or 'to allow users to specify their preferred language'. Simply stating the change is insufficient as it doesn't communicate the impact of the update.23 / 26
Liam is drafting a Slack message to announce a breaking change in an API. He writes: 'Updated the authentication service. Now uses JWT.' His teammate, Chloe, asks him if he's included details about the impact on existing clients. What should Liam add to his message to address Chloe's concern?
Chloe's question highlights the importance of communicating impact. Liam needs to explain *how* this change affects users – specifically, that clients need to update their authentication libraries. Failing to do so risks confusion and disruption for dependent systems.
24 / 26
During a code review of a new API version, Ben writes the following in the PR description: 'Implemented new rate limiting. Increased limits by 50%.' His reviewer, Maria, asks if he's explained *why* this change was made. What should Ben add to his description?
Maria's point emphasizes the importance of business context. 'Increased limits by 50%' needs to be justified – for example, 'To improve system stability and prevent abuse'. Without this rationale, developers won't understand the strategic decision behind the change.
25 / 26
Sarah is preparing a short update for her daily stand-up regarding an API change. She says: 'I updated the payment processing endpoint with a new field,
payment_method.' Her team lead asks if she can elaborate on the reason behind this addition. What should Sarah include in her stand-up update?Stand-up updates need to be concise but informative. Sarah needs to explain *why*
payment_method was added – for example, 'To support accepting payments via PayPal'. Providing this context helps the team understand the broader implications of the change.26 / 26
The API documentation describes a new endpoint: `/users/{user_id}/profile`. The response includes a field called `last_login`. A developer, Alex, is struggling to understand the purpose of this field. Which statement best reflects what should be included in the changelog entry for this update?
Alex's confusion highlights the need for clear communication. The changelog entry should explicitly state what
last_login *means* – 'This indicates the last time the user accessed their profile.' Without this explanation, the field remains ambiguous.Frequently Asked Questions
What will I practice in "API Changelog Writing | API Design Language Exercises"?
This is an API Design Language exercise set. It walks through 26 scenario-based multiple-choice questions built around real usage of API Design Language terminology that IT professionals encounter on the job.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to complete with no account, sign-up, or paywall.
How many questions are in this exercise?
This set contains 26 questions. Each one shows immediate feedback and a detailed explanation after you answer, so you learn the correct usage right away rather than waiting for a final score.
Do I need prior experience to complete this exercise?
No prior experience is required. Each question includes a full explanation covering the reasoning behind the correct answer, so the exercise itself teaches the API Design Language vocabulary as you go.
Can I retry the exercise if I get questions wrong?
Yes — use the "Try again" button on the results screen to reset your answers and go through all the questions again. There is no limit on attempts.
Is my progress saved?
Your answers and score for the current session are tracked in the browser as you go. No account or login is needed, and there is nothing to install.
What if I don't understand a term used in a question?
Read the explanation shown after you answer each question — it breaks down the correct term in plain English with a real-world example. You can also check the site Glossary for quick definitions.
How is this different from reading a blog article on the topic?
Exercises like this one are interactive drills that test and reinforce specific vocabulary through multiple-choice questions, while blog articles explain concepts in prose. Practising here after reading builds active recall, not just passive recognition.
Where can I find more API Design Language exercises?
See the API Design Language exercises hub for the full set of related pages, or browse all exercise categories from the main Exercises index.
Can I use this exercise to prepare for a technical interview?
Yes — API Design Language vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.