New JSR Proposed: Java API for RESTful Web Services

| by Stefan Tilkov Follow 5 Followers on Feb 14, 2007. Estimated reading time: 3 minutes |

Sun has submitted JSR 311, Java API for RESTful Web Services, to the JCP. According to the introduction:

This API will enable developers to rapidly build Web applications in Java that are characteristic of the best designed parts of the Web. This JSR will develop an API for providing REST(Representational State Transfer - See reference to Roy Fielding’s dissertation in section 3.1) support in the Java Platform. Lightweight, RESTful approaches are emerging as a popular alternative to SOAP-based technologies for deployment of services on the internet. Currently, building RESTful Web services using the Java Platform is significantly more complex than building SOAP-based services and requires using low-level APIs like Servlets or the dynamic JAX-WS APIs. Correct implementation requires a high level of HTTP knowledge on the developer’s part.

Supporting the JSR in addition to Sun are Apache, BEA, Doug Lea, Google, JBoss, TmaxSoft, and Jérôme Louvel, who is the creator of the RESTlet Java framework.

One of the spec leads is Sun’s Marc Hadley, who answered some questions for InfoQ.

First, we asked why he feels a REST-specific JSR is needed, i.e. why Servlets and JSPs are not enough. We also questioned the spec’s wording about low-level APIs, and how one would go about developing RESTful web apps without a deep understanding of HTTP issues and design patterns. Marc replied that while the current APIs provide broad support for HTTP, they leave a lot of work to the developer that could be automated in a higher level API:

Developers currently have to manually implement support for things like content negotiation and preconditions. A higher level API could offer default support for these and simplify the job of building a well-behaved application. In addition, current APIs don’t really highlight important things that a developer should focus on like support for the ETag and Last-Modified headers that are the basis for caching. A high level API that embodies HTTP patterns will help to lead developers down a good design path.

Concerning support for WADL, a supposedly Web-friendly description language designed by Marc, he explained that WADL is still somewhat experimental:

I think it would be premature to require support for it in the JSR. That said, I think a declarative annotation-driven approach will lend itself well to translation to and from WADL and I’d like to experiment with that outside of the JSR.

Marc confirmed that this does not mean Sun is aiming to shifts its focus from Web services (WS-*) to the Web:

Its not a question of either-or, we’ll continue to invest in both. With this JSR, we want to provide the same ease of development for RESTful services that JAX-WS and WSIT now provide for WS-* based services.

Reactions in the REST community have been mixed. In the Yahoo! REST discussion group, Elliotte Rusty Harold started a thread that echoed some harsh comments from his own blog entry:

Remember, these are the same jokers who gave us servlets and the URLConnection class as well as gems like JAX-RPC and JAX-WS. They still seem to believe that these are actually good specs, and they are proposing to tunnel REST services through JAX-WS (Java API for XML Web Services) endpoints.
They also seem to believe that “building RESTful Web services using the Java Platform is significantly more complex than building SOAP-based services”. I don’t know that this is false, but if it’s true it’s only because Sun’s HTTP API were designed by architecture astronauts who didn’t actually understand HTTP. This proposal does not seem to be addressing the need for a decent HTTP API on either the client or server side that actually follows RESTful principles instead of fighting against them.

In the same thread, Mark Baker has some criticism of his own, but concludes:

Anyhow, rather than be critical of this effort, I’ve decided to submit my application to join the EG. Java definitely needs better APIs for the Web.

XFire developer Dan Diephouse writes:

This is excellent news - I’m glad to see people are thinking more seriously about RESTful services on Java.

With the number of companies already supporting this JSR, there seems to be little doubt that it’s going to go forward through the JCP process. The current timeline expects a first draft in June 2007, and a final release in March 2008.

Pete Lacey’s reaction is probably shared by many:

  1. Cool!
  2. The servlet API is not ideal, this is needed.
  3. I hope they don’t screw it up (see JAX-WS).
Update: Marc Hadley provides some additional background in a blog entry.

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Many different ways to build services by Dan Diephouse

I've been thinking about this some more and I think one of the important things to note is that there are many ways to build services. For instance, in the SOAP world there is
1. wsdl->code
2. code->wsdl
3. JAX-WS Providers / Spring WS endpoints (granted the later is much more featureful, but the underlying basic concept is the same)

To try and define The One API for RESTful services may be a lost cause. There are even more ways I could envision building RESTful services.
- RoR style integration with existing webapp framework
- Annotation based model
- Spring MVC handlers
- Servlets
- Atom Publishing Protocol
- WADL->Code (Although some RESTafarians would probably shoot me for suggesting that heresy)

The proposal does seem to narrow this down quite a bite:

The goal of this JSR is to provide an easy to use, declarative style of programming using annotations for developers to write REST ful Web Services and also enable low level access in cases where needed by the application.

I think as long as we keep in mind the limitations of such a model, and that this will not be all things to all people, it could be OK.

For interested parties, I've done a bit of work on CXF to support using annotations/conventions to build RESTful services. Hopefully we'll be able to support whatever the JSR group comes up with as well.

Re: Many different ways to build services by Stefan Tilkov

I think the worst approach would be to start from the Java side -- the annotation idea is something I find positively repulsive. The 'right' way to do this, IMO, would be to start from the bottom up, i.e. build something that supports HTTP concepts before optionally creating a convenience layer on top.

My main objection to the Servlet API is that has everything all backwards: a single servlet with a method for each verb, responsible for handling lots of different resources. Having a Resource class as a first class citizen in the API would be much better.

And I surely hope the protocol independence bug doesn't enter into the design ...

Re: Many different ways to build services by Jerome Louvel

I agree with Stefan, it would be better to start from the bottom up. As the JSR says the main goal is to provide a set of annotations then to also "enable low level access in cases where needed by the application."

I think that the Restlet API would be a good candidate for this lower-level API. It was built with REST/HTTP/URI in mind from day one and was carefully crafter by a community of users. It does provide a Resource class that facilitates method handling, exposition of available representations, content negotiation, cache handling, etc.

I was about to submit a JSR for it when Sun proposed me to join this JSR on annotations. So I've decided to delay my submission of the Restlet JSR to 2008 to see what comes up with this higher-level JSR. If it appears to become necessary as a foundation for JSR 311, then I might reconsider this.

Re: Many different ways to build services by Dan Diephouse

I completely agree that bottom up is better. We really need a much more solid HTTP foundation in Java.

Re: Many different ways to build services by Rajith Attapattu

I think doing this inside the JAX-WS space seems to give the wrong impression. I heard that they were proposing to tunnel REST services through JAX-WS endpoints. But Dan sent me the following link to a blog post by Marc Hadley which gave me some hope.

Sun always messed it up with WS. JAX-RPC and JAX-WS were horribly complicated with no aparent benift other than to say the implementor is J2EE compliant. What a price to pay to have that check box in your marketing literature.

Anyways we already had an API for REST in the form of servlets and JSP, but I agree that they weren't enough. IMHO they should have improved these APIs and add REST support over there, not inside JAX-WS which will fuel the myth, that REST is an alternative to SOAP, instead of REST is an alternative to SOA.

After all REST API's I have seen so far, are high level annotation driven APIs on top of a HTTP binding (servlets), for example what Dan has in XFire. I strongly belive that REST support should go into an HTTP API (servlets) instead of a WS API.

Re: Many different ways to build services by Stefan Tilkov

I agree -- if REST support were part of some Web services API, this would miss the point. But what gives you the impression they're doing this "inside the JAX-WS space"?

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

6 Discuss

Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and don't miss out on content that matters to you