Wednesday, May 11, 2011

A simple REST based web service

REST stands for Representational State Transfer. Roy Fielding, the father of HTTP protocol, had coined the term in his doctoral thesis. REST is not a software, rather it is a concept or an architecture. The biggest use of REST architecture is in WWW (World Wide Web). The services that conforms to REST standard are termed as RESTful services.

REST based services contain a client and a server. The server contains resources that can be represented by various states. A client initiates the request to server when it is ready to transition it's state. The server responds with the required state.

The REST based web service is quite popular now. This type of web service is called RESTful web service. In RESTful web service we represent a service by an URI. Common HTTP methods are used to request for a specific state transfer.


CreatePUT
UpdatePOST
ReadGET
RemoveDELETE

I have used an open source java library called Jersey for creating this simple RESTful web service. Jersey is a production quality JAX-RS (JSR311) implementation. The jars from Jersey distribution need to be added to the WEB_INF/lib directory of your web application. Below is the code for a hello service -


import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/hello")
public class HelloRest {
 @GET @Produces(MediaType.TEXT_PLAIN)
 public String helloText()
 {
  return "Hello world";
 }
 @GET @Produces(MediaType.TEXT_HTML)
 public String helloHtml()
 {
  return "<html><body><h1>Hello world html</h1></body></html>";
 }
}


Here the service URI will be <web application URL>/hello as defined by the Path annotation. The GET annotation marks the service to be called on a HTTP GET request from client. The Produces annotation filters the accept type header in the request to match the correct state to be returned. It takes care of the content that is returned.


There is one more way to make the same web service. This time I'll only use URI as a representation differentiator. Below is the code-


import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/hellowithpath")
public class HelloRestWithPath {
 @GET @Path("/text")
 public String helloText()
 {
  return "Hello world";
 }
 @GET @Path("/html")
 public String helloHtml()
 {
  return "<html><body><h1>Hello world html</h1></body></html>";
 }
}

To get a HTML output the client has to make a GET request with <web application URL>/hellowithpath/html URI. Here I have only used the Path annotation.

One more thing remaining is, adding a servlet mapping in the web.xml file of the web application. Add the below mapping-

<servlet>
    <description></description>
    <display-name>ServletContainer</display-name>
    <servlet-name>ServletContainer</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>ServletContainer</servlet-name>
    <url-pattern>/rest/*</url-pattern>
  </servlet-mapping>



Once you deploy the web application in a server the RESTful services will be started. They can be tested using a browser or a http client program.

No comments:

Post a Comment