JSR 311, the Java API for RESTful Web Services (JAX-RS), is currently in its earliest stages in the JCP. This JSR is based to some extent on earlier work done by Sun on RESTful Java Web services, and an early-access version of this API is available as a NetBeans plugin that can generate RESTful services from EJB 3 entity beans.

RedHat's Bill Burke takes a thorough look at JSR 311 in a recent blog post, JSR 311, JAX-RS: Comment and suggestions:

JSR 311 does seem like it is just standardizing the REST framework Sun has already written... The spec allows you to map http header entries, query parameters, and individual elements within a URI to a method invocation and its parameters and return types. You can also specify what MIME types a method produces and consumes. The spec also provides you with the ability to define factories that can map representations to and from Java objects.

Burke points out that some aspects of the early-stage JSR 311 spec rely in method names to infer the intended Web operation; in those cases, a more explicit notation would work better, according to Burke:

@HttpMethod String getOrders()

In this example, HTTP GET would be used because getOrders() begins with the string ‘get’. I never liked the idea of magic method names. They are too fragile and IMO, just bad programming practice.

I’d like to see @HttpMethod replace[d] with a more concrete set of http annotations with the additional ability of being able to define a uri template embedded within these applications. So, instead of @javax.ws.rest.HttpMethod (or whatever the package name will be), let’s instead have individual Get, Put, Post, Delete, and Options annotations under the package @javax.ws.rest.httpmethod.

Burke also points out that JSR 311 should extend its annotation framework to the client side of a REST application as well:

The client-side programmer could use the same annotations to describe many REST web services that may or may not be using the server-side implementation of 311 or even Java at all! Doesn’t seem like much more effort to define this client-side API.

In addition, Burke notes that some sort of security considerations should be included in the context JSR 311 as well:

For instance, how about an annotation specifiying whether the resource should be accessed over HTTPS or not? How about an annotation that allows you to plug in an authentication mechanism? IMO, 311 shouldn’t be diving into defining security protocols, but should at least think about providing metadata that allows you to plug in your own implementation.

Another of Burke's comments relates to integration between restful services and the EJB spec:

I’d also like to see some work done so that EJBs can become restful as well. This will probably require some work around define lifecycle and creating an annotation like @Restful to ping the container that it needs to perform restful bindings. This would also require work with the EJB 3.1 JSR to expose JAX-RS XML descriptors within EJB 3.1.

What are your comments on JSR 311?