How do you version public web APIs?
Lobsters [Unofficial]
May 29, 2026
Often there is an existing API called something like "Product API". It often also has /api/v1 in the path.
To me this often feels like an antipattern, especially when the API itself uses semantic versioning: mixing the routes with the API contract.
Having /v1/ in the URL while also having a major.minor.patch version: coupling the first number of the semantic version to the URL path feels counter intuitive to me, if you make a breaking change, you may need new paths and new reverse proxy routes, and whatnot, and you also spread the API contract to two places, the URL and the version number.
If you start simultaneously building a brand new successor to the "Product API", the old API is effectively stuck as "v1", even if it gets breaking changes of its own.
What do you think?
Do you have any API design pet peeves or opinions to share?
Sorry for the confusing brain dump text, very interested in hearing people's opinions.
Thank you
Discussion in the ATmosphere