In the message "Versioning REST Services", dated 2007-07-05, Jim Pace wrote:
I am looking for best practices for versioning REST services. What
is the best way for a producer of information to modify/upgrade the
data format without breaking existing clients?
I have not been able to find many discussions about this issue, even though it
seems like a very fundamental problem.
In Leonard Richardson's and Sam Ruby's recently-published book,
RESTful Web Services, there is a seven paragraph discussion of this
issue in a "Service Versioning" topic within Chapter 8, "REST and ROA
Best Practices". You can find this discussion on pages 235-236 of
the book's first edition.
The authors write:
"The simplest way to incorporate the version is to make it the
first path variable: /v1/resource versus /v2/resource. ... You can
use any of the methods developed over the years for numbering
software releases. Your URI might designate the version as v1, or
1.4.0, or 2007-05022. ... If you want to get a little fancy, you can
incorporate the version number into the hostname:
v1.service.example.com versus v2.service.example.com."
This book is full of recommendations for normative practices
regarding RESTful services, many of which are similarly simple and
straightforward. One can buy the book - and make a small
contribution to the Restlet project in so doing - via this page:
http://www.restlet.org/documentation/books
Aron Roberts
