O'Reilly logo

RESTful Web Services Cookbook by Subbu Allamaraju

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

13.7. How to Version RESTful Web Services

When making compatible changes is no longer an option, version some or all resources to isolate changes from existing clients.

Problem

You want to know how to introduce a new version of a web service.

Solution

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 v1 or v2 in 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.

Discussion

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 ...

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required