API Versioning and Breaking Changes Language
Practise vocabulary for classifying API changes: breaking vs. backward-compatible, semantic versioning, deprecation, and migration language.
0 / 28 completed
1 / 28
Removing a required field from an API response is classified as a ___ change.
Removing a required field is a breaking change — existing consumers that depend on this field will fail when they receive a response without it. Breaking changes require a major version bump or coordinated consumer migration.
2 / 28
Adding a new optional field to an API response (that existing consumers don't use) is classified as an ___ change.
An additive change adds new optional content without removing or modifying existing content. Existing consumers are unaffected because they ignore unknown fields (when properly implemented).
3 / 28
In semantic versioning for APIs, a ___ version bump signals that the API change is backward-incompatible and consumers must update.
In SemVer applied to APIs: Major version = breaking changes, Minor version = new backward-compatible features, Patch = backward-compatible bug fixes. A major bump (v1 → v2) signals consumers must update.
4 / 28
A field marked as ___ in an API signals that consumers should stop using it and migrate to a replacement, before it's removed in a future version.
Deprecation marks a field or endpoint as planned for removal. It gives consumers a grace period to migrate. Good deprecation practice includes: the field still works, a migration guide exists, and a removal timeline is communicated.
5 / 28
The preferred versioning strategy that exposes the API version in the URL path (e.g., /api/v2/users) is called ___ versioning.
URI versioning (e.g., /api/v2/) makes the version explicit and visible in every request. It's the most widely used strategy because it's easy to route, debug, and document, though it duplicates URLs across versions.
6 / 28
Sarah: 'Hey team, I've just submitted a PR to update the user profile API. We've removed the `deprecated_address` field and added a new optional `preferred_language` field. Should we mark this as a breaking change? 🤔'This scenario highlights the nuance of API versioning. While simply adding an optional field isn't inherently a breaking change, removing a *required* field *is*. The key is understanding that any removal necessitates careful consideration of existing consumers who might have relied on that functionality. Incorrectly labeling it as breaking when dependencies are impacted could cause unnecessary friction and force clients into premature upgrades. The best approach here is to acknowledge the potential impact and document the change clearly.
7 / 28
David: 'I've just created a pull request to update the product catalog API. We've changed the response format to include a `total_items` field and removed the legacy `item_count` field. I'm thinking we should label this as a breaking change because consumers were relying on item_count. What's the best approach for communicating this to the team during code review?', While labeling it 'breaking' is a valid option, framing it as a change in response format is more accurate and less alarmist. Simply stating that consumers need to update their code acknowledges the potential disruption without immediately triggering panic. Options B & D are incorrect because they downplay the real impact of removing a field and ignoring the consumer's reliance on it. Option C, while direct, doesn't provide context for why the change is necessary.
8 / 28
David: 'Okay team, I've pushed a new version of the billing API. We've switched from using an integer for the `transaction_amount` to a floating-point number. Also, we've removed the authentication header 'X-Signature' and replaced it with OAuth 2.0. I'm getting some pushback about this – especially regarding the amount change. How should I frame this during the code review?'The correct answer emphasizes a pragmatic approach. While acknowledging the change is impactful, framing it as 'minor' without proper communication risks significant issues. The key here is to proactively assess consumer impact and develop a migration strategy – this demonstrates responsibility and mitigates risk. Options A and B are too forceful or technically focused; option C is dangerously dismissive, and ignoring assessment (as in option D) is a critical failure.
9 / 28
PR Description:
Subject: API v1.5 - Improved Error Handling & Data Validation
We've updated the `/orders` endpoint to include more detailed error responses and stricter data validation on request payloads. Specifically, we've added a new `validation_errors` field containing an array of error messages for invalid input, and implemented schema validation using JSON Schema. This change is designed to improve developer experience by providing clearer guidance during API usage.
Which of the following best describes the *type* of change represented in this PR description?This PR describes the introduction of schema validation and detailed error responses, which fundamentally alters how clients interact with the `/orders` endpoint. While improved error handling is beneficial, the core change—requiring consumers to adapt to a new response format and data validation rules—qualifies as a breaking change because it violates backward compatibility. Options A and D are incorrect; schema validation isn't simply an enhancement but a requirement for future API consumption. Option B incorrectly frames the changes as low risk without acknowledging the contract modification.
10 / 28
Sarah: 'Hey team, I've just submitted a PR to update the user profile API. We've removed the `deprecated_address` field and added a new optional `preferred_language` field. Should we mark this as a breaking change? 🤔'This scenario highlights the nuance of API versioning. While simply adding an optional field isn't inherently a breaking change, removing a *required* field *is*. The key is understanding that any removal necessitates careful consideration of existing consumers who might have relied on that functionality. Incorrectly labeling it as breaking when dependencies are impacted could cause unnecessary friction and force clients into premature upgrades. The best approach here is to acknowledge the potential impact and document the change clearly.
11 / 28
David: 'I've just created a pull request to update the product catalog API. We've changed the response format to include a `total_items` field and removed the legacy `item_count` field. I'm thinking we should label this as a breaking change because consumers were relying on item_count. What's the best approach for communicating this to the team during code review?', While labeling it 'breaking' is a valid option, framing it as a change in response format is more accurate and less alarmist. Simply stating that consumers need to update their code acknowledges the potential disruption without immediately triggering panic. Options B & D are incorrect because they downplay the real impact of removing a field and ignoring the consumer's reliance on it. Option C, while direct, doesn't provide context for why the change is necessary.
12 / 28
David: 'Okay team, I've pushed a new version of the billing API. We've switched from using an integer for the `transaction_amount` to a floating-point number. Also, we've removed the authentication header 'X-Signature' and replaced it with OAuth 2.0. I'm getting some pushback about this – especially regarding the amount change. How should I frame this during the code review?'The correct answer emphasizes a pragmatic approach. While acknowledging the change is impactful, framing it as 'minor' without proper communication risks significant issues. The key here is to proactively assess consumer impact and develop a migration strategy – this demonstrates responsibility and mitigates risk. Options A and B are too forceful or technically focused; option C is dangerously dismissive, and ignoring assessment (as in option D) is a critical failure.
13 / 28
PR Description:
Subject: API v1.5 - Improved Error Handling & Data Validation
We've updated the `/orders` endpoint to include more detailed error responses and stricter data validation on request payloads. Specifically, we've added a new `validation_errors` field containing an array of error messages for invalid input, and implemented schema validation using JSON Schema. This change is designed to improve developer experience by providing clearer guidance during API usage.
Which of the following best describes the *type* of change represented in this PR description?This PR describes the introduction of schema validation and detailed error responses, which fundamentally alters how clients interact with the `/orders` endpoint. While improved error handling is beneficial, the core change—requiring consumers to adapt to a new response format and data validation rules—qualifies as a breaking change because it violates backward compatibility. Options A and D are incorrect; schema validation isn't simply an enhancement but a requirement for future API consumption. Option B incorrectly frames the changes as low risk without acknowledging the contract modification.
14 / 28
Sarah: 'Hey team, I've just submitted a PR to update the user profile API. We've removed the `deprecated_address` field and added a new optional `preferred_language` field. Should we mark this as a breaking change? 🤔'This scenario highlights the nuance of API versioning. While simply adding an optional field isn't inherently a breaking change, removing a *required* field *is*. The key is understanding that any removal necessitates careful consideration of existing consumers who might have relied on that functionality. Incorrectly labeling it as breaking when dependencies are impacted could cause unnecessary friction and force clients into premature upgrades. The best approach here is to acknowledge the potential impact and document the change clearly.
15 / 28
David: 'I've just created a pull request to update the product catalog API. We've changed the response format to include a `total_items` field and removed the legacy `item_count` field. I'm thinking we should label this as a breaking change because consumers were relying on item_count. What's the best approach for communicating this to the team during code review?', While labeling it 'breaking' is a valid option, framing it as a change in response format is more accurate and less alarmist. Simply stating that consumers need to update their code acknowledges the potential disruption without immediately triggering panic. Options B & D are incorrect because they downplay the real impact of removing a field and ignoring the consumer's reliance on it. Option C, while direct, doesn't provide context for why the change is necessary.
16 / 28
David: 'Okay team, I've pushed a new version of the billing API. We've switched from using an integer for the `transaction_amount` to a floating-point number. Also, we've removed the authentication header 'X-Signature' and replaced it with OAuth 2.0. I'm getting some pushback about this – especially regarding the amount change. How should I frame this during the code review?'The correct answer emphasizes a pragmatic approach. While acknowledging the change is impactful, framing it as 'minor' without proper communication risks significant issues. The key here is to proactively assess consumer impact and develop a migration strategy – this demonstrates responsibility and mitigates risk. Options A and B are too forceful or technically focused; option C is dangerously dismissive, and ignoring assessment (as in option D) is a critical failure.
17 / 28
PR Description:
Subject: API v1.5 - Improved Error Handling & Data Validation
We've updated the `/orders` endpoint to include more detailed error responses and stricter data validation on request payloads. Specifically, we've added a new `validation_errors` field containing an array of error messages for invalid input, and implemented schema validation using JSON Schema. This change is designed to improve developer experience by providing clearer guidance during API usage.
Which of the following best describes the *type* of change represented in this PR description?This PR describes the introduction of schema validation and detailed error responses, which fundamentally alters how clients interact with the `/orders` endpoint. While improved error handling is beneficial, the core change—requiring consumers to adapt to a new response format and data validation rules—qualifies as a breaking change because it violates backward compatibility. Options A and D are incorrect; schema validation isn't simply an enhancement but a requirement for future API consumption. Option B incorrectly frames the changes as low risk without acknowledging the contract modification.
18 / 28
Sarah: 'Hey team, I've just submitted a PR to update the user profile API. We've removed the `deprecated_address` field and added a new optional `preferred_language` field. Should we mark this as a breaking change? 🤔'This scenario highlights the nuance of API versioning. While simply adding an optional field isn't inherently a breaking change, removing a *required* field *is*. The key is understanding that any removal necessitates careful consideration of existing consumers who might have relied on that functionality. Incorrectly labeling it as breaking when dependencies are impacted could cause unnecessary friction and force clients into premature upgrades. The best approach here is to acknowledge the potential impact and document the change clearly.
19 / 28
David: 'I've just created a pull request to update the product catalog API. We've changed the response format to include a `total_items` field and removed the legacy `item_count` field. I'm thinking we should label this as a breaking change because consumers were relying on item_count. What's the best approach for communicating this to the team during code review?', While labeling it 'breaking' is a valid option, framing it as a change in response format is more accurate and less alarmist. Simply stating that consumers need to update their code acknowledges the potential disruption without immediately triggering panic. Options B & D are incorrect because they downplay the real impact of removing a field and ignoring the consumer's reliance on it. Option C, while direct, doesn't provide context for why the change is necessary.
20 / 28
David: 'Okay team, I've pushed a new version of the billing API. We've switched from using an integer for the `transaction_amount` to a floating-point number. Also, we've removed the authentication header 'X-Signature' and replaced it with OAuth 2.0. I'm getting some pushback about this – especially regarding the amount change. How should I frame this during the code review?'The correct answer emphasizes a pragmatic approach. While acknowledging the change is impactful, framing it as 'minor' without proper communication risks significant issues. The key here is to proactively assess consumer impact and develop a migration strategy – this demonstrates responsibility and mitigates risk. Options A and B are too forceful or technically focused; option C is dangerously dismissive, and ignoring assessment (as in option D) is a critical failure.
21 / 28
PR Description:
Subject: API v1.5 - Improved Error Handling & Data Validation
We've updated the `/orders` endpoint to include more detailed error responses and stricter data validation on request payloads. Specifically, we've added a new `validation_errors` field containing an array of error messages for invalid input, and implemented schema validation using JSON Schema. This change is designed to improve developer experience by providing clearer guidance during API usage.
Which of the following best describes the *type* of change represented in this PR description?This PR describes the introduction of schema validation and detailed error responses, which fundamentally alters how clients interact with the `/orders` endpoint. While improved error handling is beneficial, the core change—requiring consumers to adapt to a new response format and data validation rules—qualifies as a breaking change because it violates backward compatibility. Options A and D are incorrect; schema validation isn't simply an enhancement but a requirement for future API consumption. Option B incorrectly frames the changes as low risk without acknowledging the contract modification.
22 / 28
Slack message:
@johndoe: 'Just deployed v2.0 of the payment API. The `payment_method` field is now required and uses a UUID instead of the old integer ID. Clients using the older ID format will receive 500 errors.' Should this be flagged for immediate customer support escalation?This question assesses recognizing potential impact. Changing a field from required to optional *and* changing its data type (integer to UUID) creates immediate disruption for existing clients. Options B and C are overly cautious; option A is dismissive of the real problem. Option D suggests a reactive approach instead of proactive communication.
23 / 28
Slack message:
@johndoe: 'Just deployed v2.0 of the payment API. The `payment_method` field is now required and uses a UUID instead of the old integer ID. Clients using the older ID format will receive 500 errors.' Should this be flagged for immediate customer support escalation?This question assesses recognizing potential impact. Changing a field from required to optional *and* changing its data type (integer to UUID) creates immediate disruption for existing clients. Options B and C are overly cautious; option A is dismissive of the real problem. Option D suggests a reactive approach instead of proactive communication.
24 / 28
Reviewer: 'This change to the `/users` endpoint introduces a breaking change. The `user_id` field is now an auto-incrementing integer instead of a string. Clients relying on the previous string format will need to update their code. Should we include a migration script in this PR, or is it acceptable for clients to handle the conversion themselves?'
This question tests understanding of when a breaking change necessitates more than just documentation. The key here is that changing the data type fundamentally alters how clients interact with the API – it's not just about a different name. The correct answer highlights the need for proactive client support, like a migration script, to mitigate disruption. Options B and D are incorrect because they downplay the severity of the change.
25 / 28
@alice: 'Just released v3.0 of the analytics API. We've deprecated the `/metrics/daily` endpoint and replaced it with a new GraphQL endpoint for retrieving daily metrics. The old endpoint will return 503 errors if accessed after July 1st. Any thoughts?'
This scenario focuses on proactive communication about deprecation. The correct response emphasizes the need to notify affected teams and provide a migration timeline, reflecting best practices for API evolution. Options A is too immediate; option C is an inappropriate error code; and option D ignores the breaking change.
26 / 28
Subject: API v2.1 - Schema Changes & Performance Optimization The `/products` endpoint has been updated with a new schema that includes product categories and tags. We've also optimized the database queries for faster retrieval of product data. This change will likely require clients to update their existing code that relies on the previous, simpler product structure – particularly those using the `product_id` field as a primary key. Are we providing sufficient information regarding this impact?
This tests understanding of documenting breaking changes. The core issue is that simply optimizing performance doesn't address the impact of a schema change on client code. The correct option highlights the need for a migration guide to assist clients with adapting their applications.
27 / 28
Bob: 'Just finished implementing v4.0 of the inventory API. We've changed the data format for each item to include a `serialized_details` field—a JSON blob containing all previously separate attributes. This simplifies data storage but might require clients to modify their existing code to handle this new, nested structure.' Should I schedule a brief demo for the team?
This scenario tests recognizing when client-side adaptation is necessary. While simplifying data storage is valuable, introducing a nested JSON structure *is* a breaking change. A demo clarifies the new format and helps clients adapt their code proactively.
28 / 28
Sarah: 'I've just submitted a PR to update the user authentication API. We've removed the support for legacy HTTP Basic Authentication and now exclusively use JWT. Clients using Basic Auth will receive a 401 Unauthorized error. What is the most appropriate response when reviewing this PR?',
This question assesses the understanding of a critical breaking change. Switching authentication methods fundamentally impacts client-side code and requires careful consideration of migration strategies to avoid service disruption.
Frequently Asked Questions
What will I practice in "API Versioning and Breaking Changes Language"?
This is an API Contract Testing exercise set. It walks through 28 scenario-based multiple-choice questions built around real usage of API Contract Testing 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 28 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 Contract Testing 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 Contract Testing exercises?
See the API Contract Testing 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 Contract Testing vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.