API Versioning Strategies: URL, Header, and Query Parameter Approaches

Why API Versioning Matters

API документацию are contracts between service providers and consumers. As your API evolves, breaking changes are inevitable — new fields, renamed endpoints, altered response structures, or deprecated functionality. Without a versioning strategy, every change risks breaking existing integrations and damaging trust with API consumers. A well-designed versioning approach enables evolution while preserving stability.

The Three Main Versioning Approaches

1. URL Path Versioning

The most common and visible approach, where the version number is embedded directly in the URL path.

GET /api/v1/users/123
GET /api/v2/users/123
GET /api/v3/users/123

Advantages:

• Immediately visible and self-documenting
• Easy to route at the load balancer or API gateway level
• Simple to implement in any web framework
• Cacheable by CDNs and proxies without special configuration
• Clear separation in logs, metrics, and monitoring dashboards

Disadvantages:

• Pollutes the URL namespace — the version is not part of the resource identity
• Clients must update URLs when upgrading, even if only one endpoint changed
• Can lead to code duplication across version directories if not carefully managed
• Major version bumps can feel heavyweight for minor breaking changes

2. Custom Header Versioning

The version is specified in a custom HTTP header, keeping URLs clean and resource-focused.

GET /api/users/123
Accept: application/vnd.myapi.v2+json

# Or with a custom header:
GET /api/users/123
X-API-Version: 2

Advantages:

• URLs remain clean and represent pure resource identifiers
• Follows REST principles more closely — URIs identify resources, not versions
• Allows fine-grained versioning at the resource level
• Content negotiation via Accept header is an established HTTP pattern

Disadvantages:

• Not visible in browser URLs or simple curl commands without explicit headers
• Harder to test manually and share API links
• Some CDNs and proxies may not forward custom headers correctly
• Requires more sophisticated routing logic in the API gateway
• Documentation must clearly explain header requirements

3. Query Parameter Versioning

The version is passed as a query parameter, offering a middle ground between URL and header approaches.

GET /api/users/123?version=2
GET /api/users/123?v=2

Advantages:

• Easy to add to existing APIs without restructuring URLs
• Optional parameter with a default value makes adoption gradual
• Visible in URLs for easy sharing and debugging
• Simple to implement — just read a query parameter

Disadvantages:

• Can interfere with caching if the CDN does not include query parameters in cache keys
• Mixing resource parameters with meta-parameters (version) clutters the query string
• Less discoverable than URL path versioning
• Not idiomatic for RESTful APIs

Comparison Matrix

Backward Compatibility Best Practices

Regardless of your versioning method, maintaining backward compatibility reduces the frequency of breaking version bumps:

Non-Breaking Changes (No Version Bump Needed)

• Adding new optional fields to request or response bodies
• Adding new endpoints or resources
• Adding new optional query parameters
• Adding new enum values (if clients handle unknown values gracefully)
• Increasing rate limits or quota allowances

Breaking Changes (Require Version Bump)

• Removing or renaming fields in response bodies
• Changing field data types (string to integer, array to object)
• Removing endpoints or HTTP methods
• Making previously optional fields required
• Changing authentication or authorization mechanisms
• Altering error response formats

Deprecation Workflow

A clear deprecation process respects API consumers and gives them time to migrate:

1. Announce deprecation: Add a Sunset header to responses from the deprecated version with the planned removal date. Publish a deprecation notice in your API changelog and developer portal.
2. Provide migration guides: Document every change between versions with specific before/after examples. Offer code samples for common migration scenarios.
3. Monitor usage: Track request counts per version. Contact consumers still using deprecated versions directly when possible.
4. Grace period: Maintain deprecated versions for at least 6-12 months after announcing deprecation. For enterprise APIs, 12-24 months may be appropriate.
5. Shutdown: Return 410 Gone responses after the sunset date, with a response body pointing to the migration guide and new version endpoint.

# Deprecation headers in API response
HTTP/1.1 200 OK
Sunset: Sat, 01 Mar 2026 00:00:00 GMT
Deprecation: true
Link: <https://api.example.com/docs/migration-v2-to-v3>; rel="deprecation"
X-API-Version: 2

Implementation Pattern

// Router-level version handling (PHP example)
$version = getRequestedApiVersion($request);

switch ($version) {
    case 3:
        return handleV3($request);
    case 2:
        $response = handleV2($request);
        $response->addHeader('Sunset', '2026-03-01');
        $response->addHeader('Deprecation', 'true');
        return $response;
    default:
        return errorResponse(410, 'API v1 has been retired');
}

Choosing Your Strategy

For most teams, URL path versioning is the pragmatic choice. It is simple, visible, well-supported by infrastructure tooling, and understood by every developer. Reserve header versioning for APIs where URL purity is a strong requirement or where per-resource versioning is needed. Avoid query parameter versioning for new APIs — it offers few benefits over URL path versioning while introducing caching complications.

Conclusion

API versioning is not just a technical decision — it is a commitment to your consumers. Choose a strategy early, document it clearly, maintain backward compatibility aggressively, and deprecate gracefully. The best versioning strategy is the one your team implements consistently and your consumers can follow without confusion.