Compare URL path, header-based, and content negotiation versioning, design deprecation timelines with Sunset headers, and use contract-first OpenAPI diffs.
0 / 5 completed
1 / 5
What is URL path versioning for APIs and what is its main advantage?
URL versioning: simple to implement and understand — clients know exactly which version they are calling. CDNs cache /v1 and /v2 responses independently. The downside is that changing a URL violates REST's principle that URIs identify resources, not resource versions. Stripe and GitHub use this approach for its simplicity.
2 / 5
What is header-based API versioning and what header is commonly used?
Header versioning: Stripe uses Stripe-Version: 2024-11-20 (date-based versioning). The URL stays /v1/charges forever — the header selects the API behaviour. Disadvantage: less discoverable (not visible in the URL), harder to test in a browser, and CDN caching requires the Vary: API-Version header to avoid serving wrong version responses from cache.
3 / 5
What is content negotiation versioning using the Accept header?
Content negotiation versioning: the purest REST approach — resource URIs stay stable, versions are part of the representation type. GitHub's v3 API used this with application/vnd.github.v3+json. The complexity is that many clients and frameworks don't handle versioned media types well, and CDN caching requires Vary: Accept.
4 / 5
What is an API deprecation strategy and what information should it communicate?
Deprecation strategy: the IETF Sunset header (Sunset: Sat, 01 Jan 2026 00:00:00 GMT) signals the planned decommission date machine-readably. Combined with Deprecation: true header on responses, clients can alert developers before the version is removed. Surprise deprecations erode API consumer trust.
5 / 5
What is a contract-first API versioning approach with OpenAPI?
Contract-first versioning: tools like oasdiff or Optic compare two OpenAPI specs and classify changes as breaking (removed field, changed type) or non-breaking (added field, new endpoint). Integrating schema diff into CI/CD ensures no breaking change ships without a version bump, maintaining consumer trust across API versions.