RESTful Web Services with Jersey

Representational state transfer (REST) is an architectural style for distributed hypermedia systems like the World Wide Web [1]. A fundamental concept in REST is the resource concept. A resource can be anything that has a name, e.g. a web page or search results. Another important term is the representation of a resource. A representation of a resource is a document that contains the current state of a resource: it can be XML, JSON or plain text. When a client accesses a REST service using the URI of the resource, the representation of the resource is transferred as a result of the client-server interaction. For the details of the REST architectural style please see [1]. With JSR 311 [2], a Java API for RESTful web services (JAX-RS) has been introduced. Following this specification there are now several JAX-RS implementations like CXF, Jersey, and RESTEasy.

When developing a RESTful web service with Jersey, a resource is annotated with the @Path annotation with a given URI as an argument. The methods corresponding to HTTP methods (GET, POST, DELETE, HEAD, PUT) are specified with @GET, @POST, @DELETE, @HEAD, and @PUT annotations, respectively. The resource methods should return one of javax.ws.rs.core.Response, javax.ws.rs.core.GenericEntity, void or other Java types. In addition, resource methods can throw javax.ws.rs.WebApplicationException. For an Employee manipulation web service a sample @GET method can be:

@GET
@Produces("text/plain")
	public String getEmployee(@QueryParam("id") int id)
                               throws WebApplicationException

The @Produces annotation specifies the format of the representation of Employee resources as returned by this method. The @QueryParam annotation specifies that the HTTP request parameter with name id should be passed to the method as the annotated parameter; in this case as an integer parameter with name id. The getEmployee method also throws WebApplicationException in case of errors. For example, when a GET request is received from the client where he specifies the URI as http://localhost:9998/employee_service?id=1, the getEmployee method is called with the id parameter having the value 1. Testing the @GET method is easy, since we can test the method with a browser pointing at the URI for the resource, and specifying the parameters as in the example.

@POST and @DELETE methods can be defined similarly to further manipulate Employee entities. For example:

@POST
public void createEmployee(@FormParam("method") String method,
			@FormParam("id") int id, @FormParam("name") String name)

The @FormParam annotation specifies that the parameters specified in the HTML form with name method should be passed to this method in the method parameter. To test this @POST method we can use HTTP client libraries, AJAX, or even HTML forms. With HTML forms we can use any browser to submit the given parameters to the URI of the RESTful service. Since some browsers currently do not support using HTTP DELETE with HTML forms, for testing purposes we use an additional parameter in our HTML form with name method, and submit the form with the POST method. Then in createEmployee method we check the method parameter, and take action accordingly. You can find the complete source code for the sample RESTFul Employee web service, and HTML form to test @POST methods here.

References:
1. “Architectural Styles and the Design of Network-based Software Architectures”, Roy Fielding PhD Thesis
2. JSR 311, Java RESTful Web Services Specification