An API version in an URI is fine. But better would be to use a new domain, if the API brakes backward compatibility entirely. If the API does not break the cli

An API version in an URI is fine. But better would be to use a new domain, if the API brakes backward compatibility entirely. If the API does not break the clients entirely, just have new resources for incompatible formats: /user /user2 For the first resource, you can just add a "X-Deprecated" header with a link to the deprecation information. If you already know the date when the resource is abandoned, you can also add a header that has a date of removal in it. If removed, you can either have /user serve the new format or have it serve a HTTP 303 to the new format.