🔢 API Versioning Language
Master vocabulary for API versioning strategies: URL vs header versioning, stability labels, SemVer conventions, LTS mode, and breaking change identification. Intermediate
0 / 26 completed
1 / 26
An API team debates between two versioning approaches:
- URL versioning:
GET /v2/users - Header versioning:
GET /userswithAPI-Version: 2header
Which approach is generally favoured for public APIs, and why?
Option C correctly describes the practical trade-offs that make URL versioning the dominant choice for public APIs. Both approaches have legitimate use cases:
| Dimension | URL versioning (/v2/users) | Header versioning (API-Version: 2) |
|---|---|---|
| Browser testability | ✓ Paste URL into browser | ✗ Requires curl or Postman |
| CDN caching | ✓ Different URLs cache independently | ✗ Requires Vary header; CDN support varies |
| Log readability | ✓ Version visible in access logs | ✗ Must parse headers to identify version |
| REST purity | ✗ Version in URL is conceptually mixed with the resource identifier | ✓ URL represents the resource; version is metadata |
Real-world convention: Stripe, Twilio, GitHub, and most major public API providers use URL versioning. Header versioning is more common in internal enterprise APIs where consumers are controlled. A hybrid approach is also valid: URL major version + Sunset / Deprecation headers for deprecation signalling.
2 / 26
An API changelog labels some endpoints as "stable" and others as "preview." What commitment does a "stable" label make to API consumers?
Option B correctly describes the "stable" label as a contractual commitment. The distinction between stable and preview is fundamental to API contract management:
| Label | Contract commitment | Appropriate for production use? |
|---|---|---|
| stable | No breaking changes without prior notice and migration period. Changes require a version bump. | ✓ Yes |
| preview / beta | May change without notice. Interface is not finalised. Use for evaluation only. | ⚠️ At your own risk |
| experimental / alpha | No stability guarantee. May be removed entirely. | ✗ Not recommended |
| deprecated | Scheduled for removal. Sunset date published. Migrate now. | ⚠️ Migrate before sunset date |
Why "stable" does not mean "forever": Stable guarantees process, not permanence. When a stable endpoint needs to change in a breaking way, the provider must: (1) announce deprecation, (2) publish a sunset date, (3) provide a migration path, and (4) maintain the old endpoint until the sunset date. Only then can it be removed.
3 / 26
A team debates whether REST APIs should follow semantic versioning strictly — using MAJOR.MINOR.PATCH format (e.g. v1.2.3) in the API URL. What is the typical industry convention?
Option D reflects the actual industry practice used by Stripe, GitHub, Google, AWS, and most production API teams. Using full SemVer in URLs creates unnecessary churn and confusion:
| Change type | Breaking? | URL version bump? |
|---|---|---|
| Add new optional response field | No — consumers can ignore it | No |
| Add new optional query parameter | No — backward-compatible | No |
| Add new endpoint to existing API | No | No |
| Rename required request field | Yes — existing consumers break | Yes — /v1/ → /v2/ |
| Remove a response field | Yes — consumers reading the field break | Yes — /v1/ → /v2/ |
Bug fix versioning: Bug fixes to existing endpoints (returning correct data, fixing incorrect status codes) are typically deployed without a version change — they are corrections to what the contract always promised. Only intentional, consumer-visible behaviour changes that break existing integrations require a major version increment.
4 / 26
An API changelog states: "v1 will receive security patches only until December 2026. Active feature development has moved to v2." What does this communicate to current v1 API consumers?
Option A correctly interprets the LTS / maintenance mode announcement. This vocabulary pattern is borrowed from software release management (Linux LTS, Node.js LTS) applied to APIs:
| API lifecycle phase | What consumers receive | Action for consumers |
|---|---|---|
| Active development | New features, improvements, bug fixes, security patches | Use this version for new integrations |
| Maintenance / LTS | Security patches only; no new features; no breaking changes | Plan migration to active version; existing integrations safe until sunset |
| Deprecated | May receive critical security patches; sunset date published | Migrate before sunset date |
| Sunset / EOL | Endpoint removed; returns 410 Gone or similar | Migration is mandatory — no exceptions |
What "security patches only" means for an API: Fixing vulnerabilities in the API itself (input validation, authentication bypass, data exposure). It does not mean adding new authentication schemes or changing response schemas, which would be breaking changes.
5 / 26
An API team is planning changes to the GET /v2/users/{id} response. Which change would force a major version bump and require consumer migration?
Option B is the only breaking change in the list. A change is "breaking" if it causes existing, unchanged consumer code to fail.
| Change | Breaking? | Reason |
|---|---|---|
| Add optional response field | No | Consumers that ignore unknown fields are unaffected. (Consumers that fail on unknown fields have a bug.) |
| Rename required field | Yes | All consumers reading the old field name will now get null/missing. Immediate breakage. |
| Add optional query param (default unchanged) | No | Existing calls without the parameter behave identically to before. |
| Add new endpoint | No | No existing contract is changed. |
Non-obvious breaking changes (easy to miss in code review):
- Changing a field from nullable to required
- Changing a field's data type (string → number)
- Changing date format (ISO 8601 → Unix timestamp)
- Removing an enum value from a field's allowed values
- Changing error response structure (consumers may parse error codes)
- Changing authentication scheme requirements
6 / 26
Sarah: "Hey team, I'm reviewing this PR for the new user profile API. The developer used versioning in the URL – `GET /v2/users`. It seems straightforward, but I'm not sure if it's the *best* approach.
Mark: "Yeah, URL versioning is common. It's easy to understand and implement."
David: "I think we should be using header-based versioning – `GET /users` with an `API-Version: 2` header. That's more aligned with REST principles."The question presents a realistic code review scenario. While both URL and header versioning have merit, the correct answer emphasizes that header-based versioning is generally favored for public APIs because it adheres more closely to RESTful principles – avoiding changes to the base API URL minimizes disruption for consumers. The other options misinterpret the conversation's focus; URL versioning's simplicity isn't inherently superior without considering best practices, and both approaches can be valid depending on specific requirements.
7 / 26
PR Description:
"Implemented a new endpoint for fetching user details. Versioned the API using URL segments – `GET /v2/users/{userId}`. This allows for easy backward compatibility and simplifies updates for existing clients. The schema is documented in the OpenAPI spec."This question focuses on a practical scenario: reviewing a pull request. The correct answer acknowledges that URL-based versioning (
GET /v2/users/{userId}) is a common and acceptable approach for this level of API complexity, offering good backward compatibility as described. Options A highlights the missing communication plan – a crucial element often overlooked. Option C raises a valid concern about caching implications, while option D suggests unnecessary duplication of information.8 / 26
Mark commented during a code review: "URL versioning is common. It's easy to understand and implement." David pushed back, arguing that header-based versioning (e.g., `GET /users` with an `API-Version: 2` header) is more RESTful. Which of the following statements best reflects the *primary* reason why URL versioning remains prevalent despite concerns about adhering strictly to REST principles?
URL versioning's widespread adoption stems primarily from its simplicity and ease of understanding for developers, particularly those less familiar with REST architectural nuances. While header-based versioning aligns more closely with REST principles, it introduces additional complexity in terms of HTTP parsing and requires clients to manage headers effectively. The core benefit of URL versioning is its straightforward approach: the API version is directly embedded within the URL path, eliminating the need for client-side logic to interpret or handle headers – a significant factor driving its continued use.
9 / 26
During a Slack discussion about the design of our new authentication API, Liam posted: 'Just used URL versioning – `GET /auth/v2/users`. Seems simple enough.' Maria responded with: 'URL versioning is fine for quick prototypes, but we should seriously consider header-based versioning to align better with REST best practices and avoid potential issues with long URLs.' Considering this exchange, what's the *most* significant practical reason URL versioning continues to be widely adopted despite arguments about RESTful design?
URL versioning remains popular because it provides a straightforward and intuitive approach for clients to access different versions of the API. Clients don't need to manage or parse HTTP headers; they simply include the version number in the URL. This simplicity reduces client-side development effort, which is crucial for adoption, especially among developers who may not be deeply versed in REST principles. Option C highlights a common misconception – that REST principles are rigid rules, while options A and D present overblown concerns about complexity and performance.
10 / 26
Sarah: "Hey team, I'm reviewing this PR for the new user profile API. The developer used versioning in the URL – `GET /v2/users`. It seems straightforward, but I'm not sure if it's the *best* approach.
Mark: "Yeah, URL versioning is common. It's easy to understand and implement."
David: "I think we should be using header-based versioning – `GET /users` with an `API-Version: 2` header. That's more aligned with REST principles."The question presents a realistic code review scenario. While both URL and header versioning have merit, the correct answer emphasizes that header-based versioning is generally favored for public APIs because it adheres more closely to RESTful principles – avoiding changes to the base API URL minimizes disruption for consumers. The other options misinterpret the conversation's focus; URL versioning's simplicity isn't inherently superior without considering best practices, and both approaches can be valid depending on specific requirements.
11 / 26
PR Description:
"Implemented a new endpoint for fetching user details. Versioned the API using URL segments – `GET /v2/users/{userId}`. This allows for easy backward compatibility and simplifies updates for existing clients. The schema is documented in the OpenAPI spec."This question focuses on a practical scenario: reviewing a pull request. The correct answer acknowledges that URL-based versioning (
GET /v2/users/{userId}) is a common and acceptable approach for this level of API complexity, offering good backward compatibility as described. Options A highlights the missing communication plan – a crucial element often overlooked. Option C raises a valid concern about caching implications, while option D suggests unnecessary duplication of information.12 / 26
Mark commented during a code review: "URL versioning is common. It's easy to understand and implement." David pushed back, arguing that header-based versioning (e.g., `GET /users` with an `API-Version: 2` header) is more RESTful. Which of the following statements best reflects the *primary* reason why URL versioning remains prevalent despite concerns about adhering strictly to REST principles?
URL versioning's widespread adoption stems primarily from its simplicity and ease of understanding for developers, particularly those less familiar with REST architectural nuances. While header-based versioning aligns more closely with REST principles, it introduces additional complexity in terms of HTTP parsing and requires clients to manage headers effectively. The core benefit of URL versioning is its straightforward approach: the API version is directly embedded within the URL path, eliminating the need for client-side logic to interpret or handle headers – a significant factor driving its continued use.
13 / 26
During a Slack discussion about the design of our new authentication API, Liam posted: 'Just used URL versioning – `GET /auth/v2/users`. Seems simple enough.' Maria responded with: 'URL versioning is fine for quick prototypes, but we should seriously consider header-based versioning to align better with REST best practices and avoid potential issues with long URLs.' Considering this exchange, what's the *most* significant practical reason URL versioning continues to be widely adopted despite arguments about RESTful design?
URL versioning remains popular because it provides a straightforward and intuitive approach for clients to access different versions of the API. Clients don't need to manage or parse HTTP headers; they simply include the version number in the URL. This simplicity reduces client-side development effort, which is crucial for adoption, especially among developers who may not be deeply versed in REST principles. Option C highlights a common misconception – that REST principles are rigid rules, while options A and D present overblown concerns about complexity and performance.
14 / 26
Sarah: "Hey team, I'm reviewing this PR for the new user profile API. The developer used versioning in the URL – `GET /v2/users`. It seems straightforward, but I'm not sure if it's the *best* approach.
Mark: "Yeah, URL versioning is common. It's easy to understand and implement."
David: "I think we should be using header-based versioning – `GET /users` with an `API-Version: 2` header. That's more aligned with REST principles."The question presents a realistic code review scenario. While both URL and header versioning have merit, the correct answer emphasizes that header-based versioning is generally favored for public APIs because it adheres more closely to RESTful principles – avoiding changes to the base API URL minimizes disruption for consumers. The other options misinterpret the conversation's focus; URL versioning's simplicity isn't inherently superior without considering best practices, and both approaches can be valid depending on specific requirements.
15 / 26
PR Description:
"Implemented a new endpoint for fetching user details. Versioned the API using URL segments – `GET /v2/users/{userId}`. This allows for easy backward compatibility and simplifies updates for existing clients. The schema is documented in the OpenAPI spec."This question focuses on a practical scenario: reviewing a pull request. The correct answer acknowledges that URL-based versioning (
GET /v2/users/{userId}) is a common and acceptable approach for this level of API complexity, offering good backward compatibility as described. Options A highlights the missing communication plan – a crucial element often overlooked. Option C raises a valid concern about caching implications, while option D suggests unnecessary duplication of information.16 / 26
Mark commented during a code review: "URL versioning is common. It's easy to understand and implement." David pushed back, arguing that header-based versioning (e.g., `GET /users` with an `API-Version: 2` header) is more RESTful. Which of the following statements best reflects the *primary* reason why URL versioning remains prevalent despite concerns about adhering strictly to REST principles?
URL versioning's widespread adoption stems primarily from its simplicity and ease of understanding for developers, particularly those less familiar with REST architectural nuances. While header-based versioning aligns more closely with REST principles, it introduces additional complexity in terms of HTTP parsing and requires clients to manage headers effectively. The core benefit of URL versioning is its straightforward approach: the API version is directly embedded within the URL path, eliminating the need for client-side logic to interpret or handle headers – a significant factor driving its continued use.
17 / 26
During a Slack discussion about the design of our new authentication API, Liam posted: 'Just used URL versioning – `GET /auth/v2/users`. Seems simple enough.' Maria responded with: 'URL versioning is fine for quick prototypes, but we should seriously consider header-based versioning to align better with REST best practices and avoid potential issues with long URLs.' Considering this exchange, what's the *most* significant practical reason URL versioning continues to be widely adopted despite arguments about RESTful design?
URL versioning remains popular because it provides a straightforward and intuitive approach for clients to access different versions of the API. Clients don't need to manage or parse HTTP headers; they simply include the version number in the URL. This simplicity reduces client-side development effort, which is crucial for adoption, especially among developers who may not be deeply versed in REST principles. Option C highlights a common misconception – that REST principles are rigid rules, while options A and D present overblown concerns about complexity and performance.
18 / 26
Sarah: "Hey team, I'm reviewing this PR for the new user profile API. The developer used versioning in the URL – `GET /v2/users`. It seems straightforward, but I'm not sure if it's the *best* approach.
Mark: "Yeah, URL versioning is common. It's easy to understand and implement."
David: "I think we should be using header-based versioning – `GET /users` with an `API-Version: 2` header. That's more aligned with REST principles."The question presents a realistic code review scenario. While both URL and header versioning have merit, the correct answer emphasizes that header-based versioning is generally favored for public APIs because it adheres more closely to RESTful principles – avoiding changes to the base API URL minimizes disruption for consumers. The other options misinterpret the conversation's focus; URL versioning's simplicity isn't inherently superior without considering best practices, and both approaches can be valid depending on specific requirements.
19 / 26
PR Description:
"Implemented a new endpoint for fetching user details. Versioned the API using URL segments – `GET /v2/users/{userId}`. This allows for easy backward compatibility and simplifies updates for existing clients. The schema is documented in the OpenAPI spec."This question focuses on a practical scenario: reviewing a pull request. The correct answer acknowledges that URL-based versioning (
GET /v2/users/{userId}) is a common and acceptable approach for this level of API complexity, offering good backward compatibility as described. Options A highlights the missing communication plan – a crucial element often overlooked. Option C raises a valid concern about caching implications, while option D suggests unnecessary duplication of information.20 / 26
Mark commented during a code review: "URL versioning is common. It's easy to understand and implement." David pushed back, arguing that header-based versioning (e.g., `GET /users` with an `API-Version: 2` header) is more RESTful. Which of the following statements best reflects the *primary* reason why URL versioning remains prevalent despite concerns about adhering strictly to REST principles?
URL versioning's widespread adoption stems primarily from its simplicity and ease of understanding for developers, particularly those less familiar with REST architectural nuances. While header-based versioning aligns more closely with REST principles, it introduces additional complexity in terms of HTTP parsing and requires clients to manage headers effectively. The core benefit of URL versioning is its straightforward approach: the API version is directly embedded within the URL path, eliminating the need for client-side logic to interpret or handle headers – a significant factor driving its continued use.
21 / 26
During a Slack discussion about the design of our new authentication API, Liam posted: 'Just used URL versioning – `GET /auth/v2/users`. Seems simple enough.' Maria responded with: 'URL versioning is fine for quick prototypes, but we should seriously consider header-based versioning to align better with REST best practices and avoid potential issues with long URLs.' Considering this exchange, what's the *most* significant practical reason URL versioning continues to be widely adopted despite arguments about RESTful design?
URL versioning remains popular because it provides a straightforward and intuitive approach for clients to access different versions of the API. Clients don't need to manage or parse HTTP headers; they simply include the version number in the URL. This simplicity reduces client-side development effort, which is crucial for adoption, especially among developers who may not be deeply versed in REST principles. Option C highlights a common misconception – that REST principles are rigid rules, while options A and D present overblown concerns about complexity and performance.
22 / 26
During a code review of a new user API endpoint, Mark comments: 'Using URL versioning like this – `GET /v2/users` – seems like a good starting point. It's simple to understand and maintain.' How should you respond if you believe there might be better approaches?
Mark's comment highlights a common initial instinct. While URL versioning can be simple, it's not always the *best* long-term solution. Header-based versioning offers more flexibility and avoids potential issues with URL parsing in different environments. The correct answer acknowledges this nuance.
23 / 26
Liam posts in a Slack channel: 'Just implemented the new authentication API using URL versioning – `GET /auth/v2/users`. Seems simple enough.' Maria replies: 'URL versioning is fine for quick prototypes, but what about handling major breaking changes?' What's the *most* important follow-up question Liam should consider?
Maria correctly identifies a critical consideration – backwards compatibility. URL-based versioning doesn't inherently address schema changes or breaking API versions. Liam needs to understand how the system will cope with evolving requirements and potential user migrations. Option 1 is a technical detail that's less relevant at this stage.
24 / 26
The following API response demonstrates versioning: `HTTP/1.1 200 OK Content-Type: application/json {"version": "v2", "users": [ ... ]}`. A developer asks you, 'What does the 'version' field in this response *specifically* tell me?'. What's the most accurate explanation?
The 'version' field is crucial for API versioning. It explicitly communicates which version of the API is being used, enabling clients to adapt their requests and handle changes gracefully. Options 1, 2, and 4 are either misleading or irrelevant to the function of the 'version' field.
25 / 26
A developer writes in a PR description: 'Implemented versioning for the user profiles API using URL segments – `GET /v2/users/{userId}`. This ensures compatibility with existing clients while allowing for future updates.' Which of the following statements *best* summarizes this approach?
This PR description accurately explains the core benefits of URL-based versioning: compatibility and future updates. It highlights that it's a mechanism for managing changes without disrupting existing clients. Options 2 and 3 are overly simplistic or contradict best practices, while option 4 focuses on an irrelevant metric (performance).
26 / 26
"Hey team, I'm working on the new product catalog API. I've decided to version it using URL segments – `GET /api/v1/products`. Should we discuss potential challenges with this approach during our stand-up?" How should you respond if you believe URL versioning is a suitable strategy?
The correct response acknowledges the value of proactive discussion regarding potential challenges. URL versioning can introduce complexities that warrant consideration, especially concerning backwards compatibility and scalability. The other options either discourage critical thinking or suggest prioritizing speed over sound design.
Frequently Asked Questions
What will I practice in "API Versioning Language | 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.