Which API versioning approach is most common and explicit in public REST APIs?
Options
- Version in the URL path (
/v1/orders) (Correct option) - Changing the field names silently
- Using a different port per version
- Never versioning the API at all
Answer
Version in the URL path (/v1/orders)
Why
Clients integrate against your API and break if you change it. Versioning lets you release breaking changes as a new version while old clients keep working.
Putting it in the path (/v1/, /v2/) is the most visible and common. Alternatives: a header or a query parameter.
Announce deprecations early and keep old versions running for a while.
Remember
Breaking API change → new version (/v2).