RESTful Services with Maven, Spring and Jersey

REST (REpresentational State Transfer) is an architecture style that describes how to use HTTP to access web services. JAX-RS (JSR 311) is a Java API to support implementation/access of REST web services using Java. This style was first documented by Ron Fielding. Note: Jan 10th 2012: Blog updated. Code moved into Maven project structure.

REST…

  • requires that all services be treated as resources that can be accessed via a URI.
  • requires the services be stateless.
  • does NOT describe any common data exchange formats. The producer and consumer are free to choose whatever format they want.
  • services in many cases are cacheable.
  • uses existing HTTP methods to define actions to be done on the server.

Used over HTTP the following HTTP methods can be used:

  • GET to retrieve data.
  • DELETE to delete.
  • POST to add new data
  • PUT to update data.

Now compare all of this to SOAP based web services where you use a WSDL to advertise your interface. We have the SOAP envelope that wraps the payload. Then we have document-style vs. rpc style. SOAP Faults. Marshalling and un-marshalleing the soap headers, envelope and fault. SOAP Web Services also provide many services such as transaction, security, addressing, etc (basically the WS-* baggage). And last but not the least we have the payload – finally. All that’s great, but often we just need to access a simple service without the need for all of the SOAP complexity. That is where the RESTful architecture style comes in. On the Java side JAX-RS was introduced to provide a common API to implement/access REST based services in Java. Jersey is the open source reference implementation of REST. Lets get to an example and see how this works. I will implement my usual time service. Call a service to get time of the day in XML, plain text or JSON format. First the Maven pom.xml file:

Here is the web.xml…

Here is the implementation of the TimeOfTheDayService.  JAX-WS annotations have been used to configure various JAX-RS attributes.

 

  • @Component – This is NOT a JAX-RS annotation. This is a Spring annotation to declare a spring bean via annotations vs. XML configuration
  • @Path(“/timeoftheday”) – Specifies the URI part for all the services in thisclass.
  • @GET– Used to annotate the read method.
  • @Produces(“text/plain”)– Marks the method as a producer of plain/text content.
  • @Path(“/asjson/{name}/”) – Describes the specific method. The optional {name} describes in our case the parameter passed into this service method.

Run “mvn package jetty:run” to compile and deploy the web application to a local Jetty web server. The URL to access the services would be one of:

  • http://localhost:9090/jaxrs/services/timeoftheday/asplaintext/mathew
  • http://localhost:9090/jaxrs/services/timeoftheday/asxml/mathew
  • http://localhost:9090/jaxrs/services/timeoftheday/asjson/mathew

The resource is identified via the URI and so is the parameter namein this example. Access one of the URLs mentioned above using your favorite browser and you will get the response in the appropriate format. You can also use the Jersey client API to access this service.

Once you execute this client you should get a response such as:

Click here to download the full Maven project.