Content Negotiation with Media Types
What you'll learn: How to version APIs using custom media types in the Accept header, making version selection part of content negotiation rather than part of the URL or query string.
Core Idea
Instead of embedding version information in the URI (/v2/users) or query parameters (?version=2), you can use custom media types in the Accept header. The client tells the server exactly which version and format it wants, and the server responds with the matching Content-Type.
This approach treats API versions as different representations of the same resource—just like asking for JSON vs XML, you're asking for "version 2 JSON" vs "version 1 JSON."
How It Works
The client sends:
GET /users/123
Accept: application/vnd.company.v2+json
Here, vnd.company is a vendor-specific prefix (your organization), v2 indicates version 2, and json specifies the format. The server responds with:
HTTP/1.1 200 OK
Content-Type: application/vnd.company.v2+json
Why This Approach?
- Cleaner URLs: Resource paths stay stable;
/users/123is always the same user - Follows REST principles: Leverages HTTP's built-in content negotiation mechanism
- Explicit contracts: Each media type can have its own documented schema
- Flexibility: Clients can specify fallback options:
Accept: application/vnd.company.v2+json, application/json
Trade-offs
This method is less visible than URI versioning—you can't see the version in browser address bars or logs without inspecting headers. It also requires clients to properly set headers, which some tooling may not support easily.
Key Takeaway: Custom media types in the Accept header treat API versions as content negotiation, keeping URLs clean while making version selection explicit in HTTP headers—ideal for strict RESTful designs.