Course contentsShow
← Software Engineering
Lesson 848 of 1,93326. API Contracts and DocumentationFree lesson

API Versioning Strategies

Compare URI versioning, header versioning, query parameters, and content negotiation approaches for API versions.

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.