Learn to write API changelogs: version entries, breaking change announcements, deprecation notices, and migration guides.
0 / 14 completed
1 / 14
What is a 'breaking change' announcement in an API changelog?
Breaking change announcement: 'BREAKING in v3.0: The user_id field is renamed to userId in all responses. Clients using user_id must update to userId by [date]. Migration: replace all user_id references with userId in your API response parsing code. v2.x API remains available until [sunset date].'
2 / 14
What is semantic versioning (semver) in API versioning vocabulary?
Semver for APIs: v1.0.0 → v1.1.0 (new optional field added, backward compatible) → v1.1.1 (bug fix in existing endpoint) → v2.0.0 (removed deprecated field, breaking change). Clients can safely upgrade to 1.x minor/patch versions; major version upgrades require migration planning. Semantic versioning makes version management communicable.
3 / 14
What is a 'deprecation notice' in an API changelog?
Deprecation notice: 'DEPRECATED: The GET /users/search endpoint is deprecated as of v2.3.0 and will be removed in v3.0.0 (planned Q4 2025). Migration: use GET /users?q= instead, which provides the same functionality with better performance. The deprecated endpoint will continue working until v3.0.0 release.'
4 / 14
What is 'sunset date' in API versioning vocabulary?
Sunset date: the hard deadline for removal. 'The v1 API has a sunset date of December 31, 2025. After this date, all v1 API requests will return 410 Gone.' A well-communicated sunset: announced far in advance (typically 6-12 months for widely-used APIs), includes migration guides, and uses the Sunset HTTP header in responses from deprecated endpoints.
5 / 14
What is 'additive change' vs. 'breaking change' in API evolution vocabulary?
Additive changes (safe): adding a new optional response field, adding a new endpoint, adding new enum values (with caution), relaxing validation constraints. Breaking changes: removing a field, renaming a field, changing a field type, making an optional field required, removing an endpoint, changing the HTTP method of an endpoint. The Robustness Principle: be conservative in what you send, liberal in what you accept.
6 / 14
Reviewer: 'The `getUserDetails` endpoint now returns a nested object for address information. This was an additive change – it didn't break any existing functionality.'
Which of the following best describes the reviewer's assessment in this comment, considering API changelog terminology?
The reviewer is correctly identifying an 'additive change', which refers to updates that don't affect existing API functionality. However, the explanation highlights why simply labeling it 'additive' isn't enough. A good changelog would still need to acknowledge the changed response format and advise consumers on potential compatibility issues. The key here is understanding that even seemingly minor additions can have a substantial impact when documenting API evolution for developers.
7 / 14
Reviewer: 'The `getUserDetails` endpoint now returns a nested object for address information. This was an additive change – it didn't break any existing functionality.'
Which of the following best describes the reviewer's assessment in this comment, considering API changelog terminology?
The reviewer is correctly identifying an 'additive change', which refers to updates that don't affect existing API functionality. However, the explanation highlights why simply labeling it 'additive' isn't enough. A good changelog would still need to acknowledge the changed response format and advise consumers on potential compatibility issues. The key here is understanding that even seemingly minor additions can have a substantial impact when documenting API evolution for developers.
8 / 14
Reviewer: 'The `getUserDetails` endpoint now returns a nested object for address information. This was an additive change – it didn't break any existing functionality.'
Which of the following best describes the reviewer's assessment in this comment, considering API changelog terminology?
The reviewer is correctly identifying an 'additive change', which refers to updates that don't affect existing API functionality. However, the explanation highlights why simply labeling it 'additive' isn't enough. A good changelog would still need to acknowledge the changed response format and advise consumers on potential compatibility issues. The key here is understanding that even seemingly minor additions can have a substantial impact when documenting API evolution for developers.
9 / 14
Reviewer: 'The `getUserDetails` endpoint now returns a nested object for address information. This was an additive change – it didn't break any existing functionality.'
Which of the following best describes the reviewer's assessment in this comment, considering API changelog terminology?
The reviewer is correctly identifying an 'additive change', which refers to updates that don't affect existing API functionality. However, the explanation highlights why simply labeling it 'additive' isn't enough. A good changelog would still need to acknowledge the changed response format and advise consumers on potential compatibility issues. The key here is understanding that even seemingly minor additions can have a substantial impact when documenting API evolution for developers.
10 / 14
Alex (Lead Developer) posted this message to the #api-updates Slack channel: 'Just FYI - we've updated the calculateTax function in the billing service. It now uses a different algorithm for VAT calculation due to regulatory changes.' What is Alex primarily communicating about?
The message highlights a functional change – an updated algorithm for VAT calculation. This is classified as an additive change because it doesn't fundamentally alter existing API behavior but introduces a new implementation detail. Options A, C, and D describe entirely different types of updates – security vulnerabilities, bug fixes, or complete rewrites – which are not reflected in Alex's message.
11 / 14
Sarah is drafting a PR description for a change to the `/users` endpoint. The change introduces a new field, `user_metadata`, which allows clients to store arbitrary key-value pairs related to each user. She writes: 'This enhancement adds flexibility and supports future expansion of user profiles.' Which sentence best captures Sarah's intention regarding the API evolution?
Sarah's description explicitly states 'flexibility…future expansion,' indicating an addition to the API's capabilities. This aligns with an additive change—a modification that doesn't break existing functionality but allows for new data points. Options A and D suggest breaking changes or fundamental redesigns respectively, which are incorrect.
12 / 14
David, a code reviewer, comments on a change to the API documentation:
'The previous version of the getProductDetails endpoint returned a simple JSON object with product ID and name. Now, it returns a nested object containing product details, including an `images` array and a `specifications` object. This was done to accommodate future expansion of product data.' What does David's comment primarily indicate?
David explicitly states 'to accommodate…future expansion,' which directly relates to an additive change. The introduction of new nested objects is a functional enhancement, not a breaking one that would necessitate drastic client-side modifications. Options A, D and B are incorrect as they describe different types of issues or changes.
13 / 14
Maria is writing the changelog entry for a new API version (v2.5). She needs to clearly state when the sendEmail endpoint will be fully deprecated. Which of the following phrases best represents this information?
'Sunsetted on January 1, 2024' accurately describes the end-of-life of a deprecated feature. It clearly communicates when the endpoint will no longer be supported. Options A and B are misleading; they suggest continued functionality while C is the precise definition of sunsetting. Option D is completely irrelevant to the deprecation process.
14 / 14
During a standup meeting, Ben states: 'We've updated the authentication flow to use OAuth 2.0 instead of API keys.' What is Ben communicating regarding this change?
Ben is describing an update to the *authentication flow* – a specific component within the overall system. Introducing OAuth 2.0 represents a new mechanism for authentication, making it an additive change. Options A and C are too broad while D describes a negative change.
What will I practice in "API Changelog Writing — Vocabulary and Structure"?
This is an API Spec Writing exercise set. It walks through 14 scenario-based multiple-choice questions built around real usage of API Spec Writing 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 14 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 Spec Writing 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 Spec Writing exercises?
See the API Spec Writing 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 Spec Writing vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.