API Versioning: Pick a Strategy and Stick With It
The three main API versioning approaches and when each makes sense.
Key Insights
- URL path versioning (/v1/) is the most explicit, testable, and documentable approach — pick it and move on
- Consistency matters more than which strategy you choose; all three common approaches work fine in practice
- Design APIs to minimize breaking changes — additive changes (new fields, new endpoints) don’t need version bumps
API versioning is one of those topics where people argue endlessly about the “right” approach. In practice, all three common strategies work fine — consistency matters more than which one you pick.
URL Path Versioning
GET /v1/users/123
GET /v2/users/123
Pros: Explicit, easy to route, simple to understand. Cons: Suggests the entire API changed when maybe one endpoint did.
Header Versioning
GET /users/123
Accept: application/vnd.myapp.v2+json
Pros: Clean URLs, version is metadata not resource identity. Cons: Harder to test in a browser, less discoverable.
Query Parameter
GET /users/123?version=2
Pros: Simple to implement and test. Cons: Can conflict with other query parameters, feels hacky.
My Recommendation
Use URL path versioning (/v1/). It’s the most explicit, easiest to document, and simplest to implement. Reserve major version bumps for breaking changes only.
More importantly: design your APIs to minimize breaking changes in the first place. Additive changes (new fields, new endpoints) don’t need a version bump.