RESTful WS Design Pattern

Graphical Representation:

The basics of building a RESTful webservice

It's another one of those buzz-words you seem to hear a lot of lately; RESTful webservices. REST stands for REpresentational State Transfer and is an architectural style that can already be found on the Internet since back in the days (the HTTP protocol is an example of a REST system). REST defines resources and representations. Resources can be found using a URI and generally return a representation of the data requested (In XML form, or JSON, or whatever tickles your fancy). There are all sorts of platforms that you can use to implement a REST service in Java, but for this article we'll make our own by abusing the HTTP protocol and using a servlet (which might seem crude, but it get's the idea across).

First let's lay down some principles. A REST application is all about resources. Each resource (user data, a picture, account transactions, etc.) needs at least one URI on which it can be found. There are four methods that a REST application can use, POST (update in SQL), GET (select in SQL), PUT (insert in SQL) and DELETE (delete in SQL). These do exaclty what they say and nothing more, a GET method never updates data. The service doesn't implement a state system (like HTTP does with sessions), clients should keep their own state, if necessary.

Then there's the method of communication, HTTP forms only allow PUT and GET. Even when using
AJAX you're stuck with these two, so you need to create a method of communication above the HTTP layer. Let's keep it simple in this example and say that our client is using an AJAX post to send a homemade querystring, containing a set of key-value pairs and the method to use. For example, a querystring could look like this : {GET; country=the Netherlands}. A string like this could be posted to a URI (for example where it is parsed. It could then return an XML document to the client containing, for example, all users from the Netherlands. Another example : our querystring look like this {POST, country=the Netherlands}, which is posted to the URI to update the country for the user "Pieter Heijman" to "the Netherlands" (remember, every resource has it's own URI).

When to Use REST

Architects and developers need to decide when this particular style is an appropriate choice for their applications. A RESTFul design may be appropriate when

- The web services are completely stateless. A good test is to consider whether the interaction can survive a restart of the server.

- A caching infrastructure can be leveraged for performance. If the data that the web service returns is not dynamically generated and can be cached, then the caching infrastructure that web servers and other intermediaries inherently provide can be leveraged to improve performance. However, the developer must take care because such caches are limited to the HTTP GET method for most servers.

- The service producer and service consumer have a mutual understanding of the context and content being passed along. Because there is no formal way to describe the web services interface, both parties must agree out of band on the schemas that describe the data being exchanged and on ways to process it meaningfully. In the real world, most commercial applications that expose services as RESTful implementations also distribute so-called value-added toolkits that describe the interfaces to developers in popular programming languages.

- Bandwidth is particularly important and needs to be limited. REST is particularly useful for limited-profile devices such as PDAs and mobile phones, for which the overhead of headers and additional layers of SOAP elements on the XML payload must be restricted.

- Web service delivery or aggregation into existing web sites can be enabled easily with a RESTful style. Developers can use technologies such as Asynchronous JavaScript with XML (AJAX) and toolkits such as Direct Web Remoting (DWR) to consume the services in their web applications. Rather than starting from scratch, services can be exposed with XML and consumed by HTML pages without significantly refactoring the existing web site architecture. Existing developers will be more productive because they are adding to something they are already familiar with, rather than having to start from scratch with new technology.

A SOAP-based design may be appropriate when

- A formal contract must be established to describe the interface that the web service offers. The Web Services Description Language (WSDL) describes the details such as messages, operations, bindings, and location of the web service.

- The architecture must address complex nonfunctional requirements. Many web services specifications address such requirements and establish a common vocabulary for them. Examples include Transactions, Security, Addressing, Trust, Coordination, and so on. Most real-world applications go beyond simple CRUD operations and require contextual information and conversational state to be maintained. With the RESTful approach, developers must build this plumbing into the application layer themselves.

- The architecture needs to handle asynchronous processing and invocation. In such cases, the infrastructure provided by standards such as WSRM and APIs such as JAX-WS with their client-side asynchronous invocation support can be leveraged out of the box.

RESTful Support in JAX-WS

The Java API for XML Web Services (JAX-WS) provides full support for building and deploying RESTful web services. The API was developed through the Java Community Process program asJSR 224. It is tightly integrated with the Java Architecture for XML Binding (JAXB) for binding XML to Java technology data and is included in both the Java Platform, Standard Edition (Java SE) 6 and theJava Platform, Enterprise Edition (Java EE) 5.

Building RESTful Services

JAX-WS enables building RESTful endpoints through a interface in the API. Provider is a generic interface that can be implemented by a class as a dynamic alternative to a service endpoint interface (SEI), and a service implementing this interface can be deployed in a Java EE container or published in a stand-alone mode through the JAX-WS Endpoint API.

Provider is a low-level generic API, but using it requires the endpoint to have an intimate knowledge of the desired message or payload structure being passed to the service. Depending on how the provider is implemented, the supported types for T and their uses are the following:

- javax.xml.transform.Source . Allows the provider to generate and consume XML directly

- javax.activation.DataSource . Works with MIME-typed messages

- javax.xml.soap.SOAPMessage . Conveniently works with and manipulates the entire SOAP message