There is no single "correct" answer, but there are proven strategies. Whether you choose URI pathing for simplicity or Request Headers for purity, consistency is key.
Most public web APIs (like Twitter, Google, Microsoft) use URI Versioning (e.g., /v1/users) because it is the easiest for developers to explore, debug, and cache.
However, purist REST architectures often prefer Header Versioning (e.g., X-API-Version: 1) to keep resource URLs clean. Stripe is the gold standard, using date-based header versioning with a robust backend compatibility engine.
Explore the four common implementation patterns. Click the tabs to see how the code and trade-offs change.
Who uses this?
Test your knowledge. Does this API change require a new version?
filter_by_role to the GET /users endpoint.Adding an optional parameter is backward compatible because existing clients simply won't send it, and the server will treat it as null/default.
Stripe-Version: 2024-09-30
Stripe is famous for its rolling versions. Every breaking change gets a new date. When a request comes in, their internal middleware "downgrades" the response object through a chain of transformers until it matches the date requested by the user.
X-GitHub-Api-Version: 2022-11-28
GitHub moved from pure media-type versioning to a dedicated header X-GitHub-Api-Version to make it easier for developers. They maintain strict semantic rules and provide long deprecation windows (24 months).