Course contentsShow
← Software Engineering
Lesson 793 of 1,93324. REST API DesignFree lesson

Query Parameter and Content Negotiation Versioning

Alternative versioning approaches using query strings and media type negotiation with trade-offs.

Query Parameter and Content Negotiation Versioning

You'll learn: Two alternative API versioning strategies that keep URIs clean but introduce different trade-offs around discoverability and convention.

Query Parameter Versioning

Instead of embedding version numbers in the URI path or headers, you can pass the version as a query parameter:

GET /api/users?version=2
GET /api/orders?v=1

This approach keeps your base resource URIs stable while allowing clients to explicitly request a specific API version. The version parameter is visible in the URL, making debugging easier. However, it can complicate caching (different query strings = different cache keys) and may feel less RESTful since the resource identifier changes based on representation preferences.

Content Negotiation Versioning

This strategy uses the HTTP Accept header with custom media types:

Accept: application/vnd.myapi.v2+json
Accept: application/vnd.myapi+json; version=2

The URI remains completely version-agnostic: /api/users serves different representations based on what the client requests. This is the most "RESTful" approach, treating versioning as content negotiation—like asking for JSON vs XML. However, it's harder to test in browsers, less discoverable, and requires clients to understand custom media type conventions.

Trade-offs at a Glance

Query parameters are explicit and visible but muddy resource identification. Content negotiation is elegant and RESTful but requires more sophisticated client implementation and isn't easily testable without tools. Both are less common than URI or header versioning in practice, but may suit specific architectural goals—particularly when you want stable URIs or need fine-grained representation control beyond just versioning.

Key Takeaway: Query parameter versioning makes versions visible in URLs but complicates caching; content negotiation versioning keeps URIs pure but requires custom media types and is harder to discover—choose based on your discoverability, caching, and REST purity priorities.