I have to agree with the author about not adding "v1" since it's rarely useful.

What actually happens as the API grows-

First, the team extends the existing endpoints as much as possible, adding new fields/options without breaking compatibility.

Then, once they need to have backwards-incompatible operations, it's more likely that they will also want to revisit the endpoint naming too, so they'll just create new endpoints with new names. (instead of naming anything "v2").

Then, if the entire API needs to be reworked, it's more likely that the team will just decide to deprecate the entire service/API, and then launch a new and better service with a different name to replace it.

So in the end, it's really rare that any endpoints ever have "/v2" in the name. I've been in the industry 25 years and only once have I seen a service that had a "/v2" to go with its "/v1".

> So in the end, it's really rare that any endpoints ever have "/v2" in the name.

This is an interesting empirical question - take the 100 most used HTTP APIs and see what they do for backward-incompatible changes and see what versions are available. Maybe an LLM could figure this out.

I've been just using the Dropbox API and it is, sure enough, on "v2". (although they save you a character in the URL by prefixing "/2/").

Interesting to see some of the choices in v1->v2,

https://www.dropbox.com/developers/reference/migration-guide

They use a spec language they developed called stone (https://github.com/dropbox/stone).

The author does not say that you “should not add v1”. They say that versioning is how you change your API responsibly (so, endorsing versioning), but that you should only do it as a last resort.

So you would add “v1”, to be able to easily bump to v2 later if needed, and do your best to avoid bumping to v2 if at all possible.