[smichel17]

I don't think these two are incompatible?

If APIv3 has a `/foo` endpoint that is deprecated, usually I take that to mean that the developers discourage its use, and likely plan to remove it in a future version (say, APIv4 or APIv5). `/foo` will never be removed from APIv3, because that would be a breaking change, and so if I'm willing to stay on v3 forever, that's fine, but in the (likely) event I will want to take advantage of new features at some point in the future, I'm doing myself a disservice by using /foo because it will make the migration harder.

There is at least one case where I think "deprecated" is clearly, inarguably, the right word: when the developer wants to remove a part of an API (say, because it is a large maintenance burden), but it's also committed to stability, so they won't remove that api until some acceptably small number of users are using it.