Query Parameter Versioning
What you'll learn: How to version APIs using query strings like ?version=2 and when this approach makes sense.
Query parameter versioning adds the version number directly into the URL's query string rather than the path. A request looks like /api/users?version=2 instead of /api/v2/users. The server reads the version parameter to determine which API behavior to apply.
How It Works
When a request arrives, your routing layer or middleware extracts the version from the query string. For example:
GET /api/users?version=2
GET /api/orders?version=1&limit=50
The same endpoint path handles multiple versions, branching internally based on the parameter value. If no version is specified, you typically default to the latest or a stable baseline version.
Routing Implications
Unlike URI versioning where /v1/users and /v2/users are distinct routes, query parameter versioning routes all requests to the same controller or handler. You need conditional logic inside your handler to dispatch to version-specific code paths.
Caching Considerations
This is where query parameter versioning gets tricky. HTTP caches (CDNs, browser caches, reverse proxies) treat different query strings as different resources. So /api/users?version=1 and /api/users?version=2 are cached separately—this is good for correctness but means more cache entries and potentially lower hit rates compared to completely separate paths.
When to Use It
Query parameter versioning works well when:
- Versions are optional enhancements (e.g., requesting experimental features)
- You want to keep URLs clean and avoid path clutter
- Testing multiple versions side-by-side during migration
- Internal APIs where caching complexity is manageable
Avoid it when cache efficiency is critical or when routing logic becomes too tangled with many conditional branches.
Key Takeaway: Query parameter versioning keeps paths consistent but complicates routing logic and cache management; best used when versions are optional features rather than breaking changes.