Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Debate: Does REST Need a Description Language?

Debate: Does REST Need a Description Language?

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

Rate this Article