REST

To answer this question it is important to know whether the API fully conforms to the principles of REST. A truly RESTful API uses hypermedia as the engine of application state (HATEOAS). The entire API can be used by a client that merely knows an entrypoint and the media types that are in use. Processing is guided by media types rather than the structure of the URI. Using such an architecture, the right thing to do would be to version the media types, e.g. by offering "application/vnd.someentity.v2" besides "application/vnd.someentity.v1" when breaking changes are necessary. Content Negotiation is used when a client needs a specific version.

If HATEOAS is not employed and generic media types are used, the client has to use what Roy Fielding calls out-of-band information in order to communicate which version is required. There are many ways to do that. The most popular one is to include the version number in the URI, as in "http://example.com/v1/someentity". Using query parameters or custom request headers are other means to communicate the expected version. In any case it is important to make sure that caching works, e.g. when request headers are used the Vary header should be supported.