Myth: RESTful Web Services Don't Need an Interface Definition Language
Dare Obasanjo disagrees with Steve Vinoski and Ryan Tomayko and makes the case for a REST description language:
The examples of Atom service documents and link elements in HTML, highlight that there is real world value in describing the interfaces to your RESTful Web Service. In addition, Atom service documents show that you can define an interface definition language for Web services without resorting to reinventing CORBA IDL (i.e. WSDL). So I respectfully disagree with Ryan Tomayko…just because my life is made easier with a service description language doesn’t make WSDL a good idea.
I’m not at all opposed to what Dare is suggesting — but I claim that an Atom service documents and link constructions in HTML GET forms is so wildly different from WSDL, IDL and other description formats for specialized interfaces that calling all of them “a description language” confuses the issue.
REST relies on hypermedia. An Atom service document does, too — WSDL and IDL don’t.
Totally agree. Additionally I think RESTful APIs can be compared with reflective APIs as it is possible to discover and explore such an API by using a restricted set of operations (the 4 HTTP verbs for REST and getClass(), getMethods() etc. for Java). Nobody would strike on the idea to define a domain specific interface definition for using reflection on a particular set of domain objects but would rather refer to the reflection API (for REST: HTTP spec) as well as to the application design (for REST: the protocol specification).
Instead of an IDL I would consider a BPEL pendant for REST way more reasonable. While BPEL describes the order of a set of message exchanges (that is necessary to fulfill a certain business goal), the REST world could benefit from a language that orchestrates a set of RESTful verbs in order to achieve transactions or stuff like that.
As a sign of my bigotry against all things WS-*, I’ve honestly never looked into BPEL, at all. I reckon I probably should.
w/r/t ‘calling all of them “a description language” confuses the issue.’
So, we’re down to a naming issue? Excellent. But also bad: good names are hard to come up. I recently posted to my blog the thought, again, of trying to come up with some best practices, etc for REST - names should definitely be part of that. I also recently blogged on the difficulty of naming. :-)
w/r/t ‘WSDL and IDL don’t (reply on hypermedia)’
hypermedia == something with links
I think some people consider ‘hypermedia’ to be marked up text, but I go more general. I could put a link in EXIF data in an image, and in some sense that could be considered a link by a service that parsed images and extracted the data out so it could do something. Ok, that’s a stretch. :-) Anyhoo, my definition of link is pretty vague - an address of something I can talk to, to get more information or process something. Likewise, if some service returned a piece of data for which I can construct a link - think someone returns to you a userid, and from that userid you know how to construct a URL to the user’s bookmarks, or something - that I call that a link - an odd sort of ‘relative’ link.
hmmm … from memory, a CORBA IDL could include methods that returned object references you could then use to invoke other methods, etc. Sounds like a link.
And as for WSDL - I seem to remember that looking at WSDL 2.0, they did have some ‘link’ concepts in there - it’s been a long, long time since I’ve looked at it, but if memory serves it was pretty skimpy - perhaps to the point where you’d claim it wasn’t supported at all. But the kicker is that that was WSDL 2.0 (or was it 1.2 - boy, I’ve really forgotten this stuff, and really don’t have much interest in chasing down the actual numbers), which I don’t think has been implemented widely, or perhaps at all. Someone please correct me if I’m wrong.
Despite its being a little complex and dragged through the WS-* mud, there’s nothing wrong with using XML Schema to describe message payloads (at least the XML ones). The missing piece is a method to describe the URI lexicon — at least enough to descibe URIs “at the edge of the application”. In other words, for a resource “r”, what terms are used to create valid URIs to GET/PUT/POST various data representations for “r”?
From what I recall, WADL included support for URI templates, although WADL certainly isn’t REST. My problem with looking at BPEL here is that it is scenario-driven. It describes complex interactions between systems with all the fault management and situation forking for a specific (and usually long-running) business intention. It might be too heavy-handed as a generic description vehicle.
My worry is that the spec industry, along with nature, abhors a vacuum. I hope we don’t see a rush to standardize in an area where no one seems to know what they want.
Patrick: I honestly don’t really know what a RESTful description language would look like. But I remain convinced it would not look like WSDL or IDL because they describe something else - a single endpoint with a number of methods/operations. I can’t help but feel that a REST description language would have to be distributed itself, i.e. spread across multiple resources and linked to them.
Erik: I’ll bite — why is WADL certainly not REST in your opinion?
I agree that Atom service documents and the HTML link element aren’t description languages. They are methods of autodiscovery and doesn’t really describe much other than the service’s entry points.
Wouldn’t URI Templates fit that requirement rather nicely?
Stefan:
you say:
but do you think as soon as you are going to introduce an IDL of some sort you won’t need a “resource type”. The Web needs to add actions at the “resource instance” level. Makes total sense to me, because it is based on a “Web Page” model. It has to start at that level.
In the enterprise, I don’t know a lot of things that don’t have a “type”. It is certainly not impossible to think of an enterprise where each PO and Invoice is “taylored” to each customer. But that’s going to be a hard sell to the business.
Wouldn’t a RESTian IDL be composed of (resource type, operations (QBE, actions, events), schemas of resource representations)?
JJ-
Stefan: I’d like to retract that bit — it was not accurate (and not to mention hypocritical). What I meant to say was that WADL was insufficient – at least for work I’ve been involved with. I’ve started a wish list that could be compatible with WADL, though. And since it looks like I can come to QCon, maybe we can discuss it at the pub?