REST & RESTful Web Services

REST stands for Representational State Transfer. It was introduced by Roy Thomas Fielding back in 2000 in his PhD dissertation to describe an architecture style of network system.


For the details, please refer to Roy's dissertation Architectural Styles and the Design of Network-based Software Architectures



A simplified explanation of REST

Imagine you are surfing the net and come to a web page of a nice car (a resource). The page is identified by a URL and the content is a HTML document (a representation of the car). Inside the web page, it contains other resources (e.g. tyres), which are also identified by another set URLs. When you follow one of the links and traverse to another resource, you are transferring the state to the representation of another resource.


This sequence of operations is well captured by Roy's explanation in his dissertation - "The name "Representational State Transfer" is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through the application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use."


In REST, everything is identified by a URI, and the response is a representation of the resource. It can be a HTML document, an image, or an XML document. REST is just a style of how a state changes. It is not a standard.



RESTful Web Services

REST was initially described in the context of HTTP and HTML, but it is not limited to that protocol. It has been widely adopted in the web services interfaces to become RESTful Web Services.


RESTful Web Services API is built on top of the simple HTTP request and response protocol and use the REST style for the representation state transfer. It basically uses the following HTTP methods to mimic the CRUD operations, and the payload is usually in XML or JSON.

HTTP Method CRUD operation Description
POST CREATE Create a new resource
GET RETRIEVE Retrieve a representation of a resource
PUT UPDATE Update a resource
DELETE DELETE Delete a resource


An example of creating a customer

HTTP POST request:

The body of the HTTP request contains something like:

<?xml version='1.0'?>

In response, it returns the URL of the newly created customer.


An example of retrieving the details of a customer

HTTP GET request:

The body of the HTTP response would be something like:

<?xml version='1.0'?>



Apart from the simplicity of the implementation, it still has its limitations. For instances, the payload is in XML. You may ask what kind of XML documents and where is the schema of the XML document. Unlike SOAP Web Services which are strongly typed, tools can easily discover the signature of each method and can signal any wrong doing in development phase. For RESTful Web Services, developers have to obtain the details of the interface from somewhere else, e.g. API manual.


Here is a document on how to build a RESTful Web service using JAX-WS 2.0 -