Debate: Does REST Need a Description Language?

Posted by Arnon Rotem-Gal-Oz on Jun 06, 2007 03:00 AM

Community

SOA

Topics

Web Services ,

REST

Tags

WSDL ,

Contract First Development ,

WADL

Following up on the debate of REST vs. WS-* that has yet again, been discussed here last week , it is interesting to note a debate on the topic of contracts for RESTful services that has been picking up pace over the last few days. The question that emerged was whether REST needs contracts (a la WSDLs) and even more fundamentally whether REST with contracts was still REST. It started when Aristotle Pagaltzis asked "Does REST need a service description language":

"The other day, someone posted on rest-discuss to ask whether there was a standard way to describe a REST service. This question resurfaces from time to time (and usually draws a pointer to the WADL effort as a response), which seems to indicate a popular misunderstanding of REST. I think describing a RESTful service with a WSDL-like language is a contradiction in terms..."

To which Paul Mueller responded

"We're talking about contracts here. Contracts need to be formalized, somehow. English is not the best language to use, especially since we have much more precise languages available to us.

My thoughts here are really just an extension to my thoughts on data serialization. Services are just the next level of thing that need to be meta-described."

Mark Baker followed up, agreeing with Aristotle that the only contract that REST has (and needs) is the underlying HTTP protocol with its four verbs - POST, GET, DELETE, PUT (actually, HTTP 1.1 also defined another verb - HEAD, but it isn't in wide use). Mike Herrick thought that contracts do add value

"I think that REST client developers at the very least will want schema definitions of what to expect in request/response payloads. IMHO WADL does a good job of not taking things too far. As I said, compared to WSDL it is a thing of beauty. It is so simple when the only option is HTTP (i.e., compared to the absolute insanity of protocol agnosticism). If you aren't going to use WADL, you are going to have to document the service in prose or some such. WADL at the very least seems to be a really concise way to document things."

Bobby Woolf (of Enterprise Integration Patterns fame) also believes that REST needs declared interfaces and wondered if when REST would eventually get them would the result be significantly different than WSDL John Heintz suggested to do something in between, what he called adding sign posts instead of using a description language, the idea is that the signpost would be  parsed in  run-time which would make them adaptive to changes. The crux of the matter seems to be the reliance of service consumers on the interface which is owned by the service they consume. This angle started by a comment by Stefan Tilkov who said that stubs and skeletons are problematic. Don Box replied that you need to have some reliance on the structure of the messages you get. Replying to that Stefan said

"I agree with this — my code will depend on some elements and attributes in the document. The problem, though, is that even if my application only accesses 20% of the elements and attributes in the XML it consumes, the (un)marshaling/(de)serialization code will require a perfect match between the XML and the schema that was current when the code was generated. In other words: while my application code may be tolerant to at least some changes, the generated infrastructure code isn’t "

A comment left by Mike Glendinning strengthened Stefan's point by saying that when a consumer uses 20% of the information in the return message it is effectively defining a new contract for itself. Or as Joe Gregorio notes (in a rather long Q&A style post on this whole Do we need WADL thing):

"Q: People are going to want to describe interaces, how can that be bad?

A: Yes, people want to describe interfaces, and those descriptions are brittle. If I download a WADL and compile my client today it will break tomorrow when you change the service. If, instead, you use hypertext, link following and request construction based on the hypertext and client state, then the interface won't break when you change servers, or URI structures. "

In the end the question is probably more basic than "Does REST needs formal contract or not" maybe the question is "do we need interfaces at all" consider two comments left on the above mentioned Stefan's blog . Just consider Steve Jones's comment

"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."

vs. Eric Johnson who said:

"...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..."

1. Back to top

   Beware all ye who enter unto Databinding!

   Jun 6, 2007 6:23 AM by Paul Fremantle

   One of the biggest arguments for Rest and against WS-* is that WS-* is perceived as being RPC/Stub/CORBA like. Whether or not you agree with that reading of WS-*, it is also one of the biggest benefits of WS-*. WSDL 1.x is a messy and overly complex attempt at description, but its still one of the main reasons customers opt for Web Services. The problem with WSDL and all description languages is that they inherently rely on databinding technology. And the most common schema language (XML Schema) doesn't map well into OO languages. The result is that the minute you start describing XML messages in XML Schema you have a pain point. This is being ably addressed by Paul Downey and the W3C Databinding workgroup. So what's the lesson to be learnt? If someone builds a REST description framework on top of XML Schema, they are immediately going to start to look as difficult and complex as the WS-* guys. And probably also pretty RPC-ish. So you can see why there isn't agreement here. To make REST easy for the masses, we need some tooling and description language, but to keep it loosely-coupled, simple and un-RPC we don't want to move into stubs and databinding.

   Reply

2. Back to top

   Re: Beware all ye who enter unto Databinding!

   Jun 6, 2007 7:07 AM by Arnon Rotem-Gal-Oz

   gest arguments for Rest and against WS-* is that WS-* is perceived as being RPC/Stub/CORBA like

   Right - but one can argue that the "masses" look at REST and see just see CRUD operations. (GET,POST...) also it is very easy to create URIs that are actually plain method calls that happen to use POX. I think you are likely to get RPC RESTish (i.e. not really REST) application just as much as you are likely to get them with WS-*. Of course, in both cases RPC is not the correct way to go about building Services...

   Reply

3. Back to top

   Re: Beware all ye who enter unto Databinding!

   Jun 6, 2007 8:13 AM by Stefan Tilkov

   To me, the databinding argument isn't convincing because it's not really related to the description issue, but orthogonal to it -- by now, every relevant platform has a way to consume and produce XML with both static bindings generated from XSD as well as through some other pull/SAX/DOM model. Even in WS-* land, the value code generation from WSDL adds above that from XSD is questionable; in REST, I'd claim it's nil. So if code generation is not the primary use case for a REST description language, what is? Things that come to mind are testing clients, or documentation, or compliance checks ... are those worth it? Maybe; I haven't made up my mind yet.

   Reply

4. Back to top

   REST already has contracts! Data protocols (Not programming APIs)

   Jun 6, 2007 12:21 PM by John Heintz

   Hypermedia is already a contract: a data based protocol.
   Joe's post does a great job explaining the motivation, but something Alan Dean just created a Shopping RDF example:

   To validate that the server supports the "Shop" protocol, the User Agent can test the document for the existence of the basket element, e.g. with the following XPath expression count(//shop:Basket)!=0

   To check for the "Shop" protocol, we use a data expression!
   

   Reply

5. Back to top

   Re: Beware all ye who enter unto Databinding!

   Jun 6, 2007 1:19 PM by Jean-Jacques Dubray

   Guys, let's have some fun (not) and start a new standard stack, I am wondering how different it would look like from the WS-* stack? How about rewriting the XML spec? I have a name: RML. How about rewriting XML Schema spec? XPath? anybody up to the challenge for the XSLT spec? How about REST-Security? REST-TX? REST-RX? Anybody think we can use ROL? (REST-Orchestration Language). ;-) Let me conclude: WS-* ~ REST + Metadata and as you may know, lots of people are applying REST concepts in their SOA by limiting the number of verbs for instance, or by introducing the concept of resource and resource representations weaved within their service layer.

   Reply

6. Back to top

   xml types and the Liskov principle, dynamic typing

   Jun 7, 2007 1:32 AM by Joost de Vries

   1. when a databinding supports the Liskov principle both Don Box's and Stefan Tilkovs concerns will be addressed. 2. the essence of REST to me is that it uses commoditised protocol infrastructure and API's; you don't need special development tools. Adding some form of contract description doesn't fit that model. So it probably wouldn't be beneficial. Personally I'm a bit wary that the discussion is REST vs WS-*. Imo both have their optimal spaces. And WS-* will need approx. a decade to become as commoditised as the HTTP stack. But since it's much more ambitious then REST there's no way around that. (And of course any technology that depends on generated code has the wrong architecture.)

   Reply

7. Back to top

   The theory IS correct

   Dec 31, 2008 9:34 AM by Antonio Mota

   Posted by: Steve Jones at May 29, 2007 4:13 PM

   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.

   This is for me the most compelling reason for NOT having contracts. What matters here IS the THEORY. If they are not required IN THEORY they SHOULD NOT BE USED in practice (I would say MUST NOT be used). Because that's why things break. Because the practice of today *is not* the practice of tomorrow. And if you use contracts today you are hopping for breaking something tomorrow. And the theory is well established in the Fielding dissertation. Nowhere there is to be found any reference to contracts, on the contrary it mentions the "self-descriptive messages". That if well implemented (meta-data, media-type et all) turns the need of contracts into... null!

   Reply

• Older >