API Versioning Language | API Design Language Exercises

1 / 5

An API team debates between two versioning approaches:

URL versioning: GET /v2/users
Header versioning: GET /users with API-Version: 2 header

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 / 5

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 / 5

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 / 5

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 / 5

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