Does REST Need a Service Description Language?
I think describing a RESTful service with a WSDL-like language is a contradiction in terms.
In principle, I agree; for pragmatic reasons, I believe efforts like WADL make sense, if only to have an answer to one of the most obvious questions for new REST converts :-)
I’m not a fan of WSDL, how it looks like and its complexity. But I’m still a fan of generating client stubs and server skeletons out of a service description. If you have hundreds of services, you don’t want to implement them manually, do you? At least not the xml binding. Sometimes it’s hard to find a tool in the WSDL world which works and fits your needs, but I found one (at least for my needs). In a corporate SOA world it’s crucial to have service descriptions. And I believe even with REST it’s usefull to know which “Resources” are available, what verbs they “understand” and what data (xml-schemas or mime-types, …) they expect and return. Maybe I should have a look into WADL and the Atom Publishing Protocol.
Due to the tight coupling usually created by stub and skeleton generation, I do not advocate this at all. But if you are a fan of this, at least the XML binding side is independent from WSDL, as it only relies on XML Schema. In other words: you can use e.g. JAXB with a RESTful service that consumes or produces XML, without WSDL, WADL, or any other alternatives.
Yes, that’s what makes finding a suitable framework hard to find: Loose Coupling
Contracts are a good thing, a proven good thing, I’m still confused as to why REST people don’t like them. Its almost a theory and practice thing, in THEORY they aren’t required, in practice they are.
The question is not about a contract as documentation, but rather about a contract in machine-processable form as a source e.g. for code generation. But I believe I’ll try to address this and more arguments in a follow-up post…
“if only to have an answer to one of the most obvious questions for new REST converts”
We already have that answer; HTTP 2616 does a great job at describing the interface to Web services.
Like I happened to mention in a post just today, I’m worried someone will try and prop up some sort of BPEL + URI handiwork and call it REST 1.0. It seems to me that people attracted to REST (in whatever form) are rebelling against interface-based programming more than WS-* itself — at least that’s my excuse. The constructs needed to describe REST services are already here. But making sure your URI strategy is coherent and that callers can query for relevant payload formats out-of-band is still up to you.
I’m very interested in how a “typical” REST development process looks like (if such a thing exists). Up till now I have to stick to WS-* at work. How would a cross project interaction work in the REST world? What does the service provider project team give to the service consumer project team? Just a set of URIs? How do they implement the REST service clients? Manually, using CommonsHTTPClient with an XML Mapping framework of choice? Do I stress the toolsupport too much?
Yes, I think you do — after all, do you hand over a WSDL without any accompanying documentation when you use WS-*? Chances are you provide the other team with some documentation, either inline or separate, that they have to read before using your service. A great way to document your resources is to return HTML when someone does a GET …
CommonsHttpClient is a good choice. Whether or not you need an XML binding framework is orthogonal.
Yes, you’re right. WSDL is not enough as documentation for the service consumers. Usually we provide the complete client api :) Which was not the intention from the beginning. But most colleagues ask for example code in their preferred language and not an interface description. Then we come to the question why we used WSDL in the first place? There is one thing were it really works. I use soapUI a lot for testing. Point it to your SOAP Service, append “?wsdl” and let it generate a sample request.
Things are similar around here, except that I don’t need to append “?wsdl” to get an HTML form :-)
But when do you use GET to retrieve the service documentation and when do you use GET (in a REST sense) to just read the resource? If the ID is present or not?
…I basically re-iterated Stefan Tilkov’s statement that if for pragmatic reasons only WADL makes sense…
Peter, typically an HTML representation of the resource will contain a form to interact with it, and documentation either inline or via links. The HTML is returned when a browser issues a GET (because what the content negotiation typically will lead to). When interacting with the same resource from the command line (using curl or wget) or from some other application, the Accept: header will be set to e.g. application/xml+..., and a different representation will be returned. The idea of links, though, is applicable in both cases.
I love the soul that states: “We already have that answer; HTTP 2616 does a great job at describing the interface to Web services.”
For one, I wonder how a Chinese guy accesses URIs and thinks in terms of an ASCII character set. Ops, that will change (versioning your REST enemy)
While that Form reference made me laugh (hey it is ASP.NET bloat after all), you have to note that input form does nothing on validation, very little on typing, it is absolute horror on any known infrastructure (including the ‘REST invention’ CGI :-), and as such: it strongly disables mental activity. (typing that RESTful shooting)
Furthermore, it leaves the HTML (5 is a disaster, despite attempting to solve the one above) to run scott free with invalid documents and user-agent nightmares, but hey you get some local validation that won’t matter as you will have to do it yet again on every intermediary (rand()-based safety).
Not to forget, how do you validate that form input today, still parsing strings? Are you confident to put it up on the web for every single repetition you have to do to make sure it is all ‘safe’? Great! (CGI is making a comeback but then why bother with any runtime).
And lastly a question: who on earth is making money from these debates?
Hasn’t anyone heard of people not bothering with WSDL, REST, HTTP or HTML? They make money, a lot of outfits that avoided the focus on these ‘oh-so-critical-problems’.
My point? None whatsover.
WSDL is not the problem , its not that complex. Have a look at a wsdl file..( which doesnt have the xsd type information).
The complexity resides in : 1) SOAP itself ( how it gets the WSDL) - have a look at a conversation through a network anaylyser.
2) xsd and the way different tools handle and generate these.
Wadl is pointless you may as well adopt wsdl it is well supported , but unless you fix 2 you will still be in the same boat as SOAP.
Regards,
Ben
I admit that I don’t have any idea what you mean by “how SOAP gets the WSDL”. Of course you’re right regarding WSDL’s small relevance compared to XSD. But that’s beside the point, as the discussion here was about a description language for REST — and WSDL doesn’t qualify.