I was reading a bit of Steve Vinoski’s blog on how some think REST requires a definition language like WSDL or IDL. He first mentions it within Serendipitous Reuse, and further expands on it in the blogs Lying Through Their Teeth: Easy vs. Simple, IDL vs. Human Documentation and More REST and IDL. If you are a REST fan or detractor these blogs as well as the blogs they link to are a good read and gets you thinking about things.
I’ve been implementing JAX-RS, JSR-311, off and on the past few months. Vinoski’s blogs made me think, is JSR-311 just another definition language? The language being Java + JAX-RS anotations? Maybe I’m dwelling over the obvious here, but let’s do the exercise anyways…
Vinoski paraphrases Ryan Tomayko on what might be the erroneous use of a RESTful definition language:
Among other things, Ryan touches on one of the favorite assertions of the REST detractors, which is that REST can’t be effective without an interface/service/resource definition language. After all, without such a language, how can you generate code, which in turn will ease the development of the distributed system by making it all look like a local system? Not surprisingly, the first comment on Ryan’s blog entry is exactly along these lines.
First of all, I don’t think JAX-RS is trying to make a distributed system look like a local one. Yes, its trying to remove a lot of boilerplate code. Yes, using JAX-RS could turn a POJO into a distributed RESTful resource.
public class BookStore {
@GET @Path("/books/{id}")
@ProduceMime("application/json")
public String getBook(@PathParam("id") int id) {
... return a json representation of the Book
}
}
JAX-RS does have some characteristics of a definition language. From the @GET and @Path annotations, you can determine how the resource is going to be invoked on. But, IMO though, it is more of a mapping language than a definition language. Its mapping a URI and http request/response to the invocation of a Java method. Its not trying to make our distributed system look like a local system.
Now, what about the idea I had of providing a client framework using JAX-RS annotations?
public interface BookStore {
@GET @Path("/books/{id}")
@ProduceMime("application/json")
public String getBook(@PathParam("id") int id);
}
The idea here would be you generate a RESTful client proxy from a JAX-RS annotated interface that you could invoke on without writing http client code. Are we blurring the lines here? Are we hiding too much the fact that our BookStore is a remote distributed service? I’ll leave that up to you to decide…
Bill the Plumber 
Jan 22, 2008 @ 21:11:38
Bill:
I don’t know any REST detractors. People that like WS-* generally like REST just as much. I didn’t even read any blog in the (REST+)WS-* camp telling the RESTians how and if they should build IDL at all.
I would argue that if you add annotation to an interface, you get an IDL. There is nothing wrong with it. That’s the paradox, you can create a RESTful implementation from and IDL foundation.
I think what we often forget in the discussion is that REST was designed to explain how to deal with “resource instances” (e.g. web pages -please note I say e.g. not i.e.). Never there has been the concept of a “resource type” in REST. There are representation types, but for me, the intent of media types was to enable multiple consumption types. In the old days of information systems, the question was the same: do you prefer an information representation on paper, on clay, on pyparus, on wood, on stones… Today it is PDF, XML, mp3, HTML…
So when you need to write some code, you don’t attach code to a resource instance, you need a resource type to do that.
Now, some people have started to float the idea that REST has already Service Definition Language. It is the Service Document concept in APP. So, I created the metamodel of APP: http://www.ebpml.org/blog/50.htm
It is quite amusing to see that Tim, Steve… claim that Service Document is a Service Definition, yet, when it comes to defining the interactions of a collection and member resources, they don’t define a service document, they go back to the old GET,PUT,… definitions.
It is really weird to claim you have defined some sort of service definition and the first time you could use it, you don’t. You would think eating your own dog food would be the first test you need to pass before you can make any claims.
So again, I don’t think I know anyone who is against REST, but I know a lot of people that are tired to hear that REST is vastly superior to WS-*. You may like it, don’t like it, need it, don’t need it, but they solve really different problems and trying to use one for the other’s problem doesn’t seem appealing to me, no matter how often I hear the phrase “uniform interface”.
JJ-
Jan 23, 2008 @ 21:42:09
Bill:
(I am cross-posting my comment, because something is weird with the service provider I use, obviously it is not using a RESTful implementation 🙂
you know me, we worked together. I don’t consider myself playing in the same category as you guys -I am way down there. So, I don’t understand how the discussion can be so disconnected.
This is what Steve keeps saying:
>> Like I said in my previous post, interface definition languages exist for machines to generate code. They’re totally inadequate, though, for instructing developers on how to write code to use a service.
This is what Joe G. keeps saying:
>> If I write a really good WADL for (X)HTML how close will the generated code be to a web browser? The point is that generated code stubs are so far from a completed consumer of a web service that the utility seems questionable.
Their argument is from a “Craftsman” perspective. People have done this for years, and it serves no purpose. Worse it creates brittle systems. We agree on this “craftsman” ad hoc conclusion. But this is code generation which is bad, not the IDL.
All I am saying is that
a) craftsmanship is changing. Do they know what an assembly is?
b) we cannot ignore the nature of a resource, independent of any programming model, REST, WS-*, EJB, CORBA. When I construct information systems, I see that there are indeed resources, and typically resources have a type, a set of inter-actions that include QBEs, actions, events. Can I really ignore this nature. I know I can’t.
When Steve tells you that in this opensearch document (http://bitworking.org/projects/pastebin/main.cgi/bin/8) the template is a series of character. Does it makes sense to you? How can there be such a disconnect, when clearly there are semantics embedded in the template and I can easily, trivially convert this into WSDL operation with a message type.
Am I missing something? We can’t be talking at the syntax level? right? at the semantic level, all this is isomorphic?
At the end of the day, it should be clear to everyone that “inter-actions” are a prime candidate for remote calls. Isn’t RIA and Ajax showing the way? that it is better to factor the browser-server relationship in terms of interactions rather than in terms of “pages” or “HTTP request-responses”. I can use HTTP Req/Resp to implement interactions but obviously not all HTTP Req/Resp.
This discussion could end easily by saying, yet there are a large class of applications where we don’t need to think in terms of “inter-actions” but in the realm of “information systems”, business information entities (pick your favorite term) do interact with each other and with human tasks. There is simply no other way around it.
JJ-
Nov 27, 2008 @ 12:31:57
This is good news, I’m really looking forward to playing around with it once the beta opens up.,