API Versioning Strategies

API versioning provides a mechanism for introducing breaking changes while maintaining backward compatibility for existing consumers. The three dominant strategies are URL path versioning (/api/v1/users), header-based versioning (Accept: application/vnd.myapp.v2+json), and query parameter versioning (?version=2). Each approach has trade-offs: URL versioning is the most visible and cacheable but leads to endpoint proliferation; header versioning keeps URLs clean but is harder to test in a browser; query parameter versioning is simple but can be accidentally omitted.

The most common approach in practice is URL path versioning because it is explicit, easy to route at the gateway or load-balancer level, and simple for consumers to understand. Regardless of the strategy chosen, the key discipline is defining what constitutes a breaking change -- removing a field, changing a field type, or altering validation rules are breaking; adding an optional field or a new endpoint is not. This distinction determines when a new version is required versus when changes can be made in place.

A mature versioning strategy includes a deprecation timeline (e.g., 12 months notice), sunset headers (RFC 8594), migration guides for consumers, and monitoring of traffic by version to know when old versions can be safely retired. Running multiple versions simultaneously has infrastructure and maintenance costs, so the goal is to minimize the number of active versions at any given time.