API Versioning Strategies
What you'll learn: How to compare the four main approaches for versioning APIs so you can choose the right strategy for your situation.
Core Concept
After learning why versioning matters and the difference between breaking and non-breaking changes, you need to decide how to implement versioning. There are four primary strategies, each with different trade-offs around visibility, simplicity, and flexibility.
The Four Approaches
URI Versioning (Path-Based)
Version appears directly in the URL path: /v1/users or /api/v2/products. This is the most visible and explicit approach—anyone looking at a URL knows which version they're using.
Analogy: Like different editions of a textbook on separate shelves.
Header-Based Versioning
Version specified in HTTP headers: Accept: application/vnd.myapi.v2+json. The URL stays clean, but versioning is less visible to casual observers.
Analogy: Like requesting a book in a specific language—the title stays the same, but you get a different edition.
Query Parameter Versioning
Version passed as a query string: /users?version=2. Simpler than headers but mixes versioning with other parameters.
Analogy: Like adding "large print edition" as a filter when ordering a book.
Content Negotiation
Uses the standard Accept header without custom media types: Accept: application/json; version=2. Most REST-purist but requires client sophistication.
Choosing Your Strategy
URI versioning is easiest for clients and testing. Header-based keeps URLs stable for caching. Query parameters are simple but clutter URLs. Content negotiation is elegant but harder to debug.
Most teams choose URI versioning for pragmatism, while header-based suits more mature API programs.
Key Takeaway: Each versioning strategy balances visibility, REST principles, and developer experience differently—choose based on your API's consumers and maturity level.