REST-based Web Services

REST is an acronym for the architectural style REpresentational State Transfer. Proponents of the style favour representing web service resources as URIs as opposed to using single URIs to represent the location of a whole set of services and resources. This flattened approach is in line with the architectural style of the web – the REST architectural style was described by Roy Fielding in his PhD dissertation.

The REST approach advocates the use of URIs to reference individual object instances.

The following shows how the HTTP methods, POST, GET, PUT and DELETE, can be used to provide all the actions of the CRUD (Create Retrieve Update Delete) pattern:

POST

CRUD action: CREATE

Description: Create a new resource.

GET

CRUD action: RETRIEVE

Description: Retrieve a representation of a resource.

PUT

CRUD action: UPDATE

Description: Update a resource.

DELETE

CRUD action: DELETE

Description: Delete a resource.

Of course other methods are available but those listed above are sufficient to build a complete set of web services. Note that the result of a GET action must be free of any side-effect. Consequently any action which does not create a side-effect should use the GET method.

Standards such as SOAP and XML-RPC differ from REST in their approach to web service development. Both SOAP and XML-RPC offer the ability to create new verbs for application across the network, whereas REST constrains developers to using the primitives of the web (HTTP methods listed above).

What isn’t obvious, nor talked about much in REST circles, is the issue of resource locking to overcome the issue of client update races. After posting a question, to the rest-discuss Yahoo group, enquiring about resolutions to this problem, I was pointed to the following two articles:

http://www.w3.org/1999/04/Editing/
http://www.zvon.org/tmRFC/RFC2518/Output/chapter6.html

The first of these articles describes four ways in which the update race (referred to as the Lost Update Problem in that document) can be resolved. These are:

  1. Out-of-band communication and social agreements
  2. Unreserved Checkout with Automatic Detection (UCAD)
  3. Early warning of potential future conflicts (EW)
  4. Reserved Checkout (RC)

The first of these doesn’t really work for web service development, as it really relies on personal communication of locks on resources.

UCAD, probably better known as optimistic locking, probably provides a good solution on systems that perform many reads, but only a small number of writes to a resource. Alternatively, if the client can perform a ‘merge’ operation, by obtaining and then incorporating the current state of a resource into the write operation (similar to the CVS merge feature), then this solution can also provide a good solution.

The third option, EW, doesn’t itself resolve the problem, but allows clients to determine when other reads have been performed in order to manage the problem by some other means.

Finally, RC, maybe better known as pessimistic locking, allows only one client to obtain a resource with write access; all other clients being granted read access only. This solution is probably best in situations where there is a great deal of contention for write privileges to resources.

Resources

A REST wiki, with very useful links, can be found here:
http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage

In this very compact article you’ll find the author clearly describes the REST architecture and gives a few useful examples of a web services:
http://www.xfront.com/REST-Web-Services.html

You’ll find a thorough analysis of the rest pattern compared with the SOAP approach to developing web services here:
http://www.prescod.net/rest/rest_vs_soap_overview/#fromN1012

Here’s short article on the process of developing REST-based web services:
http://www.xml.com/pub/a/2004/12/01/restful-web.html

Another article you might find useful describes the common mistakes made when design REST web services:
http://www.prescod.net/rest/mistakes/