Master the terminology behind evolving APIs without breaking existing consumers.
0 / 5 completed
1 / 5
At standup, a dev proposes releasing a new, incompatible API design as v2 while keeping the old v1 available for existing clients. What strategy is this?
API versioning lets a provider release breaking changes as a new version while continuing to support existing clients on the prior version, avoiding forcing every consumer to migrate simultaneously. It is essential for evolving a public or widely consumed API without breaking existing integrations. Multiple strategies exist for how the version is signaled.
2 / 5
During a design review, the team debates encoding the API version directly in the URL path versus in a request header. What are these two approaches called?
URL-path versioning (e.g., /v2/resource) embeds the version directly and visibly in the endpoint, while header-based versioning keeps the URL stable and signals version via a request header. Each has tradeoffs in discoverability, caching behavior, and client implementation complexity. Teams choose based on their API's consumer expectations and infrastructure.
3 / 5
In a code review, a dev adds a new optional field to a response without removing or renaming anything existing. What kind of change is this considered?
Adding an optional field that existing clients can simply ignore is typically a backward-compatible change, since it doesn't break clients written against the previous contract. This distinguishes it from breaking changes like removing or renaming a field, which do require a new version. Understanding this distinction helps teams decide when a new version is actually necessary.
4 / 5
An incident report shows clients broke when a field's data type changed within the same API version. What versioning discipline was violated?
Changing a field's data type is a breaking change even if the field name stays the same, and shipping it within an existing version without incrementing violates the implicit contract clients rely on. Breaking changes should always trigger a new version rather than silently altering an existing one. This discipline is what makes API versioning trustworthy for consumers.
5 / 5
During a PR review, a teammate asks how long the old API version should remain supported after a new one ships. What consideration should guide this?
A clear deprecation timeline, communicated well in advance, gives API consumers time to migrate while letting the provider eventually retire the maintenance burden of the old version. Balancing consumer migration needs against indefinite maintenance cost is the central tradeoff. Abrupt, uncommunicated deprecation breaks trust and client integrations alike.