The term REST, standing for Representational State Transfer, was coined by Roy Fielding in his 2000 PhD dissertation, surely one of the most influential academic studies of recent years. Fielding's dissertation title "Architectural Styles and the Design of Network-based Software Architectures" emphasizes that creating a RESTful application implies a style, or way of thinking about the problem, not a rote application of rules, but the underlying rule is that the HTTP methods of GET, POST, DELETE, PUT, OPTIONS and HEAD should each be used only for specific purposes.
Thinking about resources
The concept of Web addresses as "identifying an abstract or physical resource" (RFC 2396, 1998) is central to the concept of the World Wide Web. This concept has become rather blurred as developers have explored a variety of possibilities. Those of us who have been involved in SOAP and remote procedure call style of Web service programming sometimes have trouble adopting the REST style. There is a tendency to expect a URL to point directly to either a process or a discrete file on the server. The following quote from Fielding's dissertation shows how different the REST view is:
The resource is not the storage object. The resource is not a mechanism that the server uses to handle the storage object. The resource is a conceptual mapping — the server receives the identifier (which identifies the mapping) and applies it to its current mapping implementation (usually a combination of collection-specific deep tree traversal and/or hash tables) to find the currently responsible handler implementation and the handler implementation then selects the appropriate action+response based on the request content. All of these implementation-specific issues are hidden behind the Web interface; their nature cannot be assumed by a client that only has access through the Web interface.
Contrasting SOAP versus REST requests
The central problem of a Web service is interpreting a request and routing
it to the correct process so that the desired representation if returned. SOAP-based
services not only have to look at the request headers, but also have to parse the XML formatted request body and return XML formatted text.
RESTful services only have to examine the request headers and URL to determine
the process to handle the request and the resource representation to return. It is
important to remember that a given resource can have several different representations.
For example, an appointments calendar might be returned as text, HTML, XML, PDF or
an image.
The increasing industry buzz about REST has induced developers of Web service related tools such as standards, language libraries, and IDEs to explore new ideas. We see
either attempts to incorporate REST into existing tools or totally new approaches. First, let's look at REST in recent specification efforts.
REST in the WSDL 2.0 specification
In recognition of the number of developers turning away from SOAP to the REST style, the W3C working group incorporated what they term "HTTP support" in the recently released WSDL 2.0 specification. This version, many years in the making, is a major revision of version 1.0 with reorganization supposed to reduce complexity. In theory, a WSDL 2.0 document can describe a service as both a SOAP and a REST application. The tools previously used to create Web services from WSDL documents will need major modification to work with WSDL 2.0.
WADL - a new approach
One of the open-source projects being carried out under the GlassFish umbrella is WADL - the Web Application Description Language. A WADL document gives an XML formatted description of a REST style Web service suitable for machine processing to create a Java client. Provision is made for flexible description of the resources and the paths to reach them.
JAX-RS the Java API for RESTful Web services,
This specification, being developed as JSR 311 under the Java Community Process approach, is at the "Editors Draft" stage, with the latest version released in December 4, 2007. It is still incomplete with many unresolved issues. The intent is to use Java annotations in POJO (plain old Java object) classes so that they can be exposed as RESTful Web resources. Using annotations of course requires Java version 1.5 or later, which should not be a problem for most users. JAX-RS does not provide for service discovery or assist in client side programming, but does promise compatibility with existing servlet containers and the JAX-WS group of tools.
Specification by plain text
Before we get all wound up in some XML service description language, lets drop back a bit and think about simplicity.
Yahoo's documentation on creating a REST Request just relies on a text description loaded with examples. The various search services have their own vocabulary, sure, but they in turn have simple text explanations. A REST purist would say that the Yahoo requests are not 100% REST because they use a URL query formatting, including a parameter to specify the desired representation rather than a request header. Whatever, it gets the job done and Yahoo provides examples and SDKs for a number of different languages.
Programmer's view
Right now, if I had to write a simple RESTful Web service, I would just write my own Java servlet implementation of the request interpretation. For describing the service so other people could build clients, I would write a plain text explanation supplemented with a WADL description. However, maybe I will change my mind when I review the latest programmer's toolkits for the next article.
Resources
This Wikipedia article contains a list of well known services that provide REST style developer interfaces.
A conversation about REST
More on WADL including a Yahoo example
