Why Version At All
APIs evolve, and a breaking change can shatter existing clients. Versioning lets old and new behavior coexist while callers migrate on their own schedule. The main question is where the version lives.
URL Versioning
Put the version in the path, such as slash v2 slash orders. It is visible, easy to test in a browser, and simple to route. The downside is that the same resource now has two URLs, which dilutes the idea that a URL names one thing.
Header Versioning
Send the version in a header such as Accept with a vendor media type. URLs stay clean and a resource keeps one address, but the version is hidden, harder to test by hand, and easy to forget.
Choosing
- Use URL versions for public APIs where visibility and caching matter.
- Use header versions when you want clean URLs and disciplined clients.
- Either way, change the version only for breaking changes.
Key idea
Versioning isolates breaking changes; URL versions are visible and cacheable while header versions keep URLs clean, and you bump only on breaking changes.