Header-Based Versioning
What you'll learn: How to use HTTP headers to specify API versions while keeping your URLs clean and resource-focused.
The Core Idea
Header-based versioning moves version information out of the URL and into HTTP headers—either a custom header like API-Version: 2 or the standard Accept header with content negotiation (e.g., Accept: application/vnd.myapp.v2+json).
This approach keeps your URLs purely about resources, not implementation details. The same URL (/api/users/123) serves different response structures based on which version the client requests in headers.
How It Works
Custom Header Pattern:
GET /api/users/123
API-Version: 2
Accept Header Pattern:
GET /api/users/123
Accept: application/vnd.myapp.v2+json
The server inspects these headers and routes the request to the appropriate version handler. If no version header is provided, you typically default to the latest stable version or return an error requiring explicit versioning.
The Trade-offs
Advantages:
- URLs remain resource-centric and clean—no
/v1/or?version=2clutter - Aligns with REST principles (resources shouldn't change URLs based on representation)
- Supports content negotiation alongside versioning
- Easier to cache resources under a single URL with header-based cache keys
Disadvantages:
- Less discoverable—you can't just look at a URL in logs or browser history to see the version
- Harder to test manually (can't just paste URL in browser)
- Requires header inspection infrastructure and careful cache configuration
When to Use It
Ideal for mature APIs where developer experience includes proper HTTP client libraries, and you want strict separation between resource identity and version.
Key Takeaway: Header-based versioning keeps URLs pristine and resource-focused by moving version negotiation into HTTP headers, trading some discoverability for architectural cleanliness.