When making compatible changes is no longer an option, version some or all resources to isolate changes from existing clients.
You want to know how to introduce a new version of a web service.
Add new resources with new URIs when there is a change in the
behavior of resources or a change in the information contained in
representations. Use easily detectable patterns such as
subdomain names, path segments, or query parameters to distinguish
URIs by their version.
Avoid treating each version as a new representation with a new media type of the same resource.
Versioning a RESTful web service involves versioning resources with new URIs. This is because HTTP dictates everything except URIs of resources and their representations. Although you can add custom HTTP methods and headers, as discussed in Recipe 1.12 and Recipe 1.13, such additions may impair interoperability with other clients and servers. This leaves you with resources for versioning.
Here are some URIs using version identifiers:
http://www.example.org/v1/customer/1234 http://www.example.org/v2/customer/1234 http://www.example.org/customer/1234?version=v3 http://v4.example.org/customer/1234
Of these, what works best may depend on your software stack and server deployment. When the same server manages multiple versions, then using path segments or query parameters may be convenient.
Consider the email example from Recipe 13.2. Since the email field is new ...