The problem with the REST folks these days is that they are just hell-bent on having constructive conversation all the time. This piece should have been the pudding-pack that started the cafeteria food fight but, no, everyone decides to concentrate on the one concrete critique of WS-* mentioned in the entire rant, kicking off a level-headed debate about description languages, documentation, and service discovery.
First, Steve Vinoski puts forth a blatantly logical piece on WSDL, IDL, and documentation grounded in actual real world experience:
Proponents of definition languages seem to assert that such languages help with understandability. Such languages, they say, are required because they alone tell you how to invoke the service, what to pass to it, and what to expect in return. The problem with the way they make this assertion, though, is they make it sound like the application figures all that stuff out on its own with no human involvement. What happens in reality is that an actual human programmer sits down, reads the interface definition, more than likely reads some comments in the definition or a whole separate document that describes the interface in more detail, and perhaps even talks to the person who wrote the interface definition in the first place. Based on the knowledge gained, he then writes the application to call that interface.
What a jerk!
Next, Patrick Mueller makes a half-assed attempt at disagreeing with Steve or something but eventually falls in line with yet more constructive crap regarding documenting REST-style interfaces:
We all agree that documentation is good. Do you think there's some kind of a standard 'template' that we might agree on, that could provide all the practical, required information regarding usage of REST services? All text, prose, for now; just identify the information actually required. That seems like a worth-while goal, especially to try to educate people on the "way of REST" - and I'm talking about RESTy service providers here. Lots of people don't get REST. Let's teach them, by example, and by the way, I'm sure I still have a lot to learn myself.
(Not to encourage this type of discussion or anything but, if we're voting on Best REST Documentation, mine goes to the Blinksale API Reference.)
Luckily, you can always count on Dare Obasanjo (he's also known as Carnage4Life for heaven's sake) to get the flame-throwers going, right? Right?!
Nope. He tries to be contentious but fails miserably when he makes a really good point about how useful discovery is:
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.
Well I'm going to have to disrespectfully agree with you on that one. So there!
Of course, Stefan Tilkov isn't going to let Dare get away with it:
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.
Bah! You people are hopeless.
No wonder Mark's decided to tender his resignation after eight years of service to the Loyal Opposition.
On a semi-serious note, it appears that contemporary thinking on these topics has coalesced in the years since I was last actively following the discussion, and in a very good way. Here's what I think I've learned about what people are thinking:
WSDL is basically every bad idea anyone ever had related to service documentation/description, schema, and/or discovery all rolled nicely into a document classified as a "recommendation".
Documentation is really important. We should do more of that. Just because WSDL sucks doesn't mean ignoring documentation/description is okay.
Automated/machine discovery is really useful. We should do more of that. Just because WSDL sucks doesn't mean we should ignore discovery.
Schemas can be useful when placed far enough up the stack. (i.e., don't bake schema and language binding in at the protocol level.) Just because WSDL sucks doesn't mean describing representations using some formal schema is a bad idea.
That's a promising set of assumptions. Godspeed!
Previous Topic
