REpresentational State Transfer or REST
REST is essentially a philosophy of web service architecture, not a standard like SOAP. Emphasis is on strict interpretation of the roles of the various actions; GET, PUT, POST and DELETE and the other features defined in the HTTP 1.1 protocol. I discussed the perceived virtues of the REST approach in this article more than two years ago. Since that time we have seen continued growth in support for REST style services such as Amazon's S3 service and Google's Data APIs.
As the standards associated with SOAP have gotten more and more complex, developers have been attracted to REST. This enthusiasm for REST has led to many services getting called RESTful when in fact they are a shallow gloss over a RPC style. For example, strictly speaking, a GET operation should only get a representation of a resource without modifying it. The ActiveMQ open source messaging server allows GET operations to read a message which is then erased but claims a RESTful interface. You can find lots of arguments in developer blogs and forums as to whether or not a particular service is RESTful. To simplify, I am trying to stick to Fielding's original idea and the HTTP1.1 specification.
The Essentials of RESTful Architecture
The following table, table 5.1 in Fielding's dissertation, gives the various data elements in RESTful architecture with modern examples. The HTTP 1.1 protocol provides many features potentially useful in web services. For example, services which are able to read and use the If-Modified-Since HTTP header in a request can avoid duplicating output of an unchanged resource. Services which return an image should be able to interpret the Accept HTTP header to return the client's preferred media type. It seems reasonable to expect that any formal descriptive language for RESTful web services should cover as many of these "data elements" as possible.
Data Element |
Modern Web Examples |
|
|
resource |
the intended conceptual target of a hypertext reference |
resource identifier |
URL, URN |
representation |
HTML document, JPEG image |
representation metadata |
media type, last-modified time |
resource metadata |
source link, alternates, vary |
control data |
if-modified-since, cache-control |
How to Describe a REST Service
At the present time, the big services such as Yahoo, Amazon, Google and Flickr communicate their HTTP interfaces to potential developers primarily with text descriptions and example code. This has proven sufficient for lots of examples to be created but lacks the professional air you get with formal standards. and prevents use of automated tools and formal SOA relation definitions.
The Web Services Description Language - WSDL
WSDL version 1, was first published as a W3C "note" rather than a standard. Version 1.1, published in 2001, before interest in RESTful style web services really got started, has been used in a variety of toolkits for coding SOAP services and clients but did not provide for REST style service descriptions.
WSDL version 2, a W3C recommendation released in June 2007 makes some attempt to accomodate REST but continues to emphasize SOAP. The published standard does not even give a REST example but I found this Wikipedia article which gives a RESTful interface example in WSDL. The idea appears to be to map various REST style HTTP requests onto SOAP. It makes no provision for selecting the media type of the representation to be returned. I suspect that this approach will only be used when you have to expose the same service with both SOAP and REST. Initial reaction in the REST developer community to WSDL 2.0 does not seem to be very enthusiastic.
The Web Application Description Language - WADL
WADL is an attempt to define an XML formatted description of HTTP based services that is both machine and human readable and no more complex than it needs to be. The latest draft revision of the WADL specification, which was just released in February, contains several important changes. Apparently, experience with the Java based Jersey RESTful service toolkit is providing feedback on useful features so this is far from a standard set in concrete. The WADL specification addresses how to document the following features of a RESTful web service.
- The resources offered and how to build a URL to address each one.
- The HTTP methods (GET, POST, etc.) supported.
- The parameters and their schema types which can appear in requests
- The response representations (media types)
- Additional documentation in plain text or XHTML markup.
Conclusion
Neither WSDL or WADL address all aspects of RESTful services as identified in Fielding's dissertation. Some important features REST could provide are not mentioned at all. Right now a lot of people are happily exploring RESTful services without any commitment to a standard descriptive language. In my opinion, although WSDL may work for some simplified cases, cramming all the parameters needed to describe all REST style operations into the WSDL 2.0 format is probably impossible. WADL is looking pretty good but the specification and tools to make use of it are in early stages.
Resources
Fielding's Dissertation, a valuable resource for understanding REST and evolution of HTTP specifications.
This Wikipedia article contains many references to REST design discussions.
Wikipedia article on WSDL 2.0 including an attept to define a "RESTfulInterface" with WSDL.
WADL project at Java.net.
Home page for the open source Jersey RESTful Web Service implementation.
More on WADL including a Yahoo example
