Versioning Strategies

API versioning is the mechanism that allows the API to evolve without breaking existing consumers. The versioning strategy is a one-way door — once consumers are building against /v1/, changing the versioning scheme is a breaking change to the versioning system itself. Three strategies dominate production APIs, and each makes different trade-offs between consumer simplicity, producer flexibility, and operational overhead.

1. URL Path Versioning /v1/orders, /v2/orders. The version is visible in the URL. Consumers know exactly which version they are calling. The trade-off: the URL changes with every major version, which breaks bookmarks and requires client updates. The benefit: unambiguous, simple to route, easy to monitor version adoption. This is the most common strategy and the right default for public APIs.
2. Header Versioning The version is specified in a request header: Accept: application/vnd.company.v2+json. The URL remains stable. The trade-off: the version is invisible in logs and bookmarks, harder to test with browser tools, and requires header-aware routing. The benefit: clean URLs and the ability to negotiate content type alongside version.
3. Query Parameter Versioning /orders?version=2. Simple to add and test. The trade-off: mixing version metadata with business query parameters is semantically messy. The benefit: works with any HTTP client without header configuration. Acceptable for internal APIs; avoid for public APIs where URL cleanliness matters.