1) The specification has “Entity Providers” which allow you to encapsulate the mapping between objects and the wire format. Please travel the links I provided in the blog for more information. As far as your “separation” concern, I don’t think its a big deal. If you want the decoupling just have your Restful webservice delegate to a POJO, EJB, or Spring bean. Also, the separation is another reason I want to be able to restfully annotation interfaces instead of just the bean class. IN EJB I always saw the interface as the view you wanted to publish over a particular protocol.

2-4) Thanks for the suggestions. I’m a total REST noob, have never written a RESTful application, so its good to hear best practices and such.

I really like your analysis and suggestions but there are few code smells that remain for me. Perhaps you simply haven’t covered all these things.

1) Formatting - It seems to me that the annotations assign specific output and input mime types. This breaks the model of separating presentation from behaviour that we get from MVC, doesn’t it? Why should my code care if the client wants XML or JSON or HTML or PDF for that matter? Same with incoming data. It seems to me that what is needed is some standard facility to take incoming data (either as JSON, XML or HTTP parameters (get & post) and convert it into some standard structure that can be consumed by my methods. In addition, I should be able to assign some set of views to the output of my method to the format required by the client. Rails does an excellent job of this.

2) Verbs - As Ryan pointed out, its necessary to be able to handle arbitrary verbs to do new things. In addition, browsers are not RESTful clients since users can only create POST and GET requests, some standard facility for “faking” PUT and DELETE with a POST will be useful. Yes, I know that you can do PUT and DELETE using AJAX; that only means that XMLHTTPRequest is a restful client. Perhaps I should say HTML User Agents.

3) Adjectives - Often its beneficial to supply an adjective to the request. For example, normally I’d POST to /blogs/123/posts/12210/comments to create a new comment. However if I want to get a preview of my comment then I’ve seen it suggested that I want to post to /blogs/123/posts/12210/comments;preview. That is create a real, but temporary, comment and return it. Another example is if I’m making requests from a browser for HTML. If I ask for /blogs/123/posts/12210 then I get the post, but if I want to edit it, I’m stuck, unless I can ask for /blogs/123/posts/12210;edit.

4) Pluralization - Personally I think that you should GET from /blogs for a list of blogs and /blog/123 for a specific blog.

Re: the relationship between the implementation (Jersey, at http://jersey.dev.java.net) and the Specification, the implementation follows the specification, but it also helps try things out and ensure the specification is implementable and useful. But definitively, the specification drives the implementation, not the other way.

- eduard/o

javax.ws.rest.httpmethod.@Get, etc….
javax.ws.rest.webdevmethod.@Whatever

Then what you have is typesafe and the compiler can catch typos rather than waiting for deployment or runtime to find the problem. Its also great for IDE’s autocompletion as well. Have @HttpMethod as a fallback just in case new methods are added in the future maybe, i don’t know.

No, I don’t like the @UriTemplate(”MKCOL”, “/shopping/orders/{ID}” syntax either.

In regards to the @Get, @Post, @Delete, @Put annotations: the idea is great but it could also be limiting as well. The idea behind the @HttpMethod is that allows an implementation to use lesser used HTTP methods as well as those from the WebDAV spec. Therefore, one could do:

@HttpMethod("MKCOL")
@UriTemplate("/shopping/orders/{id}")
public void buy(Orders orders) {...}


If we went the annotation approach, we’d need to define an annotation for every possible method. An hybrid approach could be:

@UriTemplate("MKCOL","/shopping/orders/{id}")
public void buy(Orders orders) {...}


But then it looses some of the readability.

Eric:

JAX-RS does work quite nicely with JAXB. In fact, the spec mandates that a provider must include a JAXB Element Entity Provider. So you are not limited to working with raw Documents. Otherwise, this would suck

* @UriTemplate is definable at class level
* @UriTemplates sounds good. I’ll ping Heiko
* Pretty sure JAXB bindings are there too. There are provider plugins and XML is one of them.

Sorry I didn’t go in deeper. I’m pretty sure the links I provided here should give a lot more detail on the spec. I just wanted to focus on specific things I want to add.