JSR 311 Final: Java API for RESTful Web Services

Posted by Stefan Tilkov on Sep 24, 2008

Sections

Architecture & Design,

Development,

Enterprise Architecture

Topics

REST ,

SOA ,

Java

Tags

Web services ,

API ,

URI ,

HTTP

In February 2007, Sun announced JSR 311 : The Java API for RESTful Web services. Yesterday, the draft 1.0 specification passed the JCP EC approval ballot , which essentially means it is now final.

JAX-RS is an annotation-based API for implementing RESTful web services , based on HTTP, in Java. Essentially, classes and methods are annotated with information that enables a runtime to expose them as resources - an approach that is very different from the one exposed by the servlet programming model. A runtime that implements JAX-RS mediates between the HTTP protocol and the Java classes, taking into account URIs, requested and accepted content types, and HTTP methods. In addition to the Sun-provided reference implementation, Jersey , other implementations are available (in various stages of completion): as part of the popular Restlet framework, the JBoss RESTeasy project , and as part of the Apache CXF web services stack.

InfoQ spoke to the spec leads, Sun’s Marc Hadley and Paul Sandoz about their view on JAX-RS and the process.

Asked how happy they are with the result, Marc said he’s pretty satisfied with how the API has turned out. He also considers it very fortunate that so many implementations were built while the expert group was working on the API and that this has really helped to smooth out any rough edges. Paul added that there were developers willing to play with versions of the API, give those implementations a test drive, and provide feedback.

When asked about the most challenging aspects, Marc pointed out that initially, it was hard to get a consensus on the style and scope of the API:

To jumpstart the JSR we started with a fairly comprehensive proposal but in retrospect I think we might have been better to start with something more skeletal and build from there.
In the last few months we’ve seen a lot of interest in the JSR and the main challenge was sticking to our schedule while accommodating all the new input.

Paul dared to question some aspects of the “J” in JSR:

Perhaps this is somewhat heretical but sometimes I find the current Java language syntax itself a bit of a challenge. However, via Java annotations, generics and builder patterns i think we managed to get things down to a very concise level. What’s more it is possible write such JAX-RS applications easily in Scala and Groovy, both of which have Java byte-code compatible annotation support.

When the JSR was initiated, there were some doubts in the REST community about its chance of complying with REST’s key principles. Marc thinks this goal has been met:

I think the API encourages a resource-centric view and makes developers think about the identifiers of their resources and the methods they support. Declarative support for content negotiation works well and the default resource life-cycle encourages a stateless approach. If I had to identify a weakness it would have to be limited support for hypermedia as the engine of state - whilst we provide good support for extracting information from request URIs and building URIs to resources, its still very much left to the developer to use hypermedia in representations appropriately.

Paul agreed:

Yes, this is probably the hardest area. JAX-RS provides a bunch of ways to construct URIs but there is no such URI binding facility with a modeling API, such as JAXB. I think there are some aspects we can explore in this respect, for example Henry Story’s RDF serialization.

Questioned whether the work on JSR 311 has changed his opinion on the Web and Web Services, Marc noted it had confirmed his opinion that one can do “an awful lot with HTTP without recourse to more complex things”. Paul pointed to REST inventor Roy Fielding’s use of a sparse bit array for notifications as an example of one of the pleasant surprises REST still has in store.

We also asked Marc how he expects JSR 311 to influence the upcoming Servlet spec revision:

A JAX-RS application can be hosted in a Servlet container so its important that the two work together well. JAX-RS is a potential customer of the new Servlet pluggability framework so we’ve been providing input on that. One tricky aspect is that JAX-RS provides more flexible URI to resource mapping than is possible for Servlets and this makes it a challenge to use declarative Servlet security with JAX-RS so we’re working on that too.

Finally, Marc confirmed that Jersey is not “just” a reference implementation, but definitely usable for production, and that there are live deployments already. He also pointed out that Jersey will be the Glassfish JSR 311 implementation and needs to be production quality because of this. Paul emphasized another reason:

One of the advantages of regular early access releases of the specification and implementation was that both the API and implementation got battle tested early and often :-)

You can check out the specification online; the Jersey reference implementation is available on java.net and works on Java 5 or higher.

1. Back to top

   REST client API

   by Sean Sullivan

   When I last looked at JAX-RS, it did not include an API for REST clients. Are there plans to address this in a future JSR?
   
   
   
   
   FYI - the JBoss RESTEasy project has a REST client API:
   org.jboss.resteasy.client.core

   Reply

2. Back to top

   Re: REST client API

   by Stefan Tilkov

   No, there is no client API in JAX-RS – it was considered pretty late in the process, but the EG deemed time too short to do a good job of it. Jersey has a client API too.
   
   
   I'm pretty sure a future JSR will address it, but I wouldn't hold my breath …

   Reply

• Older >