Comment by ad_hockey

A couple of considerations are:

- You have to decide whether to bump the entire API version or only the /foo endpoint. The former can be a big deal (and you don't want to do it often), the latter is messy. Especially if you end up with some endpoints on /v1 (you got it right first time) while others are on /v4 or /v5. Some clients like to hard-code the URL prefix of your API, including the version, as a constant.

- You still have to decide what your deprecation and removal policy will be. Does there come a time when you remove /api/v1/foo completely, breaking even the clients who are using it correctly, or will you support it forever?

It's not easy at all, especially if you have to comply with a backwards compatibility policy. I've had many debates about whether it's OK to introduce breaking changes if we consider them to be bug fixes. It depends on factors like whether either behaviour is documented and subjective calls on how "obviously unintended" the behaviour might be.