API versioning strategies: header, URL, and content negotiation

API versioning is one of those decisions where every option is defensible and every option is wrong in the right context. For a public REST API serving mixed web and mobile clients at roughly 50M requests per day, the three realistic strategies are URL path versioning, custom header versioning, and content negotiation through the Accept header. Picking between them is less about theoretical purity and more about how your clients, caches, and logs actually behave. URL path versioning puts the version in the resource path, for example /v1/users and /v2/users. It is the most discoverable option — every developer reading a log line, a stack trace, or a curl command sees the version immediately. CDNs and reverse proxies route it naturally because the version is just part of the cache key. The weakness is philosophical: REST purists argue that /v1/users and /v2/users should represent the same resource, not different ones. In practice that concern rarely pays rent, and the operational simplicity wins. Custom header versioning sends something like X-API-Version: 2 on each request. It keeps URLs clean and lets the same URL evolve, but it introduces real operational pain. CDN cache keys must now include the header, which is easy to misconfigure. Log analysis tools that group by path suddenly need to parse headers. Mobile clients that forget to send the header get the default version, which silently breaks when you change the default. Debuggability suffers. Content negotiation via Accept: application/vnd.company.v2+json is the most RESTful approach and the one most likely to cause an outage. It pushes versioning into a place most tooling does not inspect, and subtle differences between application/json and the vendor media type can produce bewildering behavior. The one scenario where it shines is when different clients need different response shapes of the same resource — truly a content concern rather than a version concern. Recommendation: use URL path versioning for the major version and a supplementary header (X-API-Minor: 3) for additive minor changes that never break clients. Treat major versions as commitments with an 18-month deprecation window, emit Deprecation and Sunset response headers the moment a version enters its twilight, and maintain a public changelog. At scale, the operational clarity of seeing /v2/users in every log entry is worth more than theoretical elegance.