Course contentsShow
← System Design
Lesson 1901 of 1,91945. API Design and VersioningFree lesson

Header-Based Versioning

Using custom or Accept headers for version negotiation while maintaining clean URLs.

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=2 clutter
  • 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.