URL versioning vs header versioning
URL versioning embeds the API version in the URI path (/v1/users, /v2/users) or query string (?version=2). Header versioning communicates the desired version through an HTTP header — typically Accept: application/vnd.api+json;version=2 or a custom X-API-Version: 2 header. Both approaches are valid; the choice depends on trade-offs between discoverability, cacheability, and client complexity.
Why it matters in practice
URL versioning is the most common approach for public REST APIs because it is visible, easy to test in a browser, supported by all HTTP clients without special configuration, and unambiguously cacheable by CDNs (the URL uniquely identifies the resource version). Header versioning keeps URLs clean and allows content negotiation, but requires clients to configure custom headers and makes it harder to share links or see which version a cached response belongs to. For internal APIs where clients are known and controlled, header versioning is a reasonable choice; for public APIs, URL versioning is the safer default.
Common mistakes
- •Using header versioning for public APIs that are cached by CDNs — most CDNs cache by URL and ignore request headers, meaning all header-versioned requests hit the same cache entry regardless of version.
- •Not including the version in error responses for URL-versioned APIs — a 400 from /v1/users should identify itself as a v1 error in the response body.