RESTful Web Services Made Easy

Representational State Transfer (REST) has become a popular approach to developing web services. Many developers see the REST architectural style as much simpler than SOAP, the prevalent web services approach before REST. A lot of that simplicity is the result of some basic concepts that underlie REST. For example, everything in REST is seen as a resource that is identified by a Universal Resource Identifier (URI). And REST presents a standard set of methods with which you communicate with a resource through a uniform interface.

The Java API for RESTful Web Services (JAX-RS) is a technology that makes it easy for Java developers to build RESTful web services -- web services that adhere to the REST architectural style. The latest release of JAX-RS, JAX-RS 1.1, will be included in Java EE 6, the next version of Java Platform, Enterprise Edition. In the 2009 JavaOne Conference technical session titled, Developing RESTful Web Services With the Java API for RESTful Web Services (JAX-RS), Sun engineers Marc Hadley and Paul Sandoz, the specification leads for JAX-RS, presented the basics of the technology and demonstrated how easy the technology is to use.

Hadley handled the tutorial part of the session, which started with a discussion of basic concepts. One of the most important underpinnings of JAX-RS is that it's annotation based. So typically, a lot of the work in building a RESTful web service with JAX-RS is simply creating and annotating Plain Old Java Objects (POJOs) -- in other words, simple Java classes. Each of these classes represents a resource in JAX-RS. Hadley noted, however, that resources do not necessarily have to be classes. "If you're in an EE container, you can use EJBs [Enterprise JavaBeans]."

For example, the code for a resource in JAX-RS might look something like this:

   
    @Path ("properties");       
    public class SystemProperties {
      @GET  
      LIST<SystemProperty> getProperties (...) {...}
                
      @Path("{name}")
      SystemProperty getProperty (...) {...}           
    }    

The @Path annotation for the class specifies a relative URI path for the resource, and the @Path annotation for the method specifies a relative URI for the resource returned by the method. The @GET annotation indicates that the resource responds to HTTP GET requests. In supporting the REST style, JAX-RS provides a standard set of methods that support HTTP PUT, POST, and DELETE requests. Hadley said that REST does not require a fixed set of methods. "It's supposed to be a small set of standard methods, but WebDAV extends that set." However, Hadley advised developers to use the methods that are already defined and not to start making their own. "If you start making methods up, clients probably won't know about them, and client libraries won't know how to produce the methods."

Requests and responses in JAX-RS contain resource representations in formats identified by media types. These media types include XML, JSON, HTML, XHTML. For example, a GET request that produces XML might look like the following:

   @GET 
   @Produces("application/properties+xml")
   Property getXML(@PathParam("name") String name)
   {...}   

As you might guess, the @Produces annotation specifies the media type of representation that a resource can produce, in this case XML. JAX-RS also includes a @Consumes annotation that specifies the media type of representation sent by the client that a resource can consume. Note that these annotations are for doing static content negotiation. JAX-RS also supports dynamic negotiation.

One other thing to keep in mind is that responses contain URIs that link to further resources. For example, a response that contains XML might look something like the following:

   HTTP/1.1 201 CREATED
   Date: Wed, 031 Jun 2009 16:41:58 GMT
   Server: Apache/1.3.6
   Location: http://example.com/properties/foo
   Content-Type: application/jorder+xml
   Content Length: 184
   
   <property self="http://example.com/properties/foo">
      <parent ref="http://example.com/properties/bar">
      <name>Foo</name>
      <value>1</value>
   </order>   

Hadley then focused on deployment options provided by JAX-RS. The JAX-RS specification identifies two ways for deploying JAX-RS resources. A JAX-RS application can be deployed on a Java Platform, Standard Edition (Java SE) endpoint. In this case, the deployer needs to supply some configuration information such as a list of resource classes and providers.

In Java EE, a JAX-RS application can be packaged in a WAR file just like a servlet. In addition, a resource class can be deployed as an EJB session bean or a singleton bean. When a Java EE container becomes JAX-aware, the web.xml file can be used to directly find resource classes for deployment. For containers that are not JAX-aware, deployers have to do some additional configuration.

Perhaps most impressive in this session was a set of JAX-RS demonstrations that Sandoz showed using NetBeans 6.7 (currently available as an RC2 download) and GlassFish v3 Preview. GlassFish v3 Preview is an open-source application server that implements Java EE 6. Sandoz showed how easy it is to create and change JAX-RS resources, and then deploy and run applications that use the resulting RESTful web services. Sandoz told the audience that what they should get out of these demonstrations is the idea that "it's easy to play with and test your assumptions in JAX-RS." He indeed proved the point.

Hadley ended the session with a JAX-RS roadmap. The JAX-RS 1.0 specification was finalized in October 2008. Work on a maintenance release, JAX-RS 1.1, is completed. Work has also begun on a new functional release, JAX-RS 2.0, which will include significant enhancements such as the inclusion of a client API.

You can get more information about JAX-RS and its reference implementation, Jersey, at the following locations:

» JSR 311: JAX-RS: The Java API for RESTful Web Services
» JSR 311 Project
» Jersey Home Page
» Marc Hadley's Blog
» Paul Sandoz's Blog
» Jakub Podlesak's Blog

» Java EE 6 Technologies
» Download Java EE 6 SDK Preview with GlassFish v3 Preview

Do you have comments about this article? We welcome your participation in our community. Please keep your comments civil and on point. You may optionally provide your email address to be notified of replies - your information is not used for any other purpose. By submitting a comment, you agree to these Terms of Use.