There’s a flurry of discussion about whether or not, in the world of REST, you need some sort of formal specification for the services you’re offering. My conclusion: yes, but in a very application-specific way.
If you want to read up on the debate, check out Sam Ruby and Ryan Tomayko (who’s hilarious while being insightful) and follow some pointers. But the piece that made the penny drop for me was Dare Obasanjo’s Myth: RESTful Web Services Don't Need an Interface Definition Language.
I’ve always had this internal voice telling me that Web Services do really need some sort of a way to declare them. I can remember, years and years ago, Nelson Minar saying “All I want is a .h file for my Web Service” and thinking yes.
WSDL clearly isn’t the answer, but that’s because WSDL sucks, deeply and totally. I have had hopes for WADL, and still do. But I have to say, it hasn’t been fully obvious to me how you’d actually use such a beast. So I had this little voice in the back of my head muttering “YAGNI”.
Then after reading Dare’s piece, it dawned on me that I just spent the last three years of my life helping develop a Web Service Specification language, namely the Atom Publishing Protocol’s Service Document. Plus, I’ve written a bunch of software that processes them.
But... the APP Service Doc is totally specific to the needs of one particular RESTian protocol. So, we have existence proof that there is at least one useful instance of a service declaration. We do not really have existence proof that such a thing can be generalized across the needs of multiple protocols or applications.
Contributions
Comment feed for ongoing:
From: Robert Sayre (Jan 18 2008, at 18:35)
HTML forms are service declarations.
[link]
From: David Illsley (Jan 20 2008, at 23:53)
"We do not really have existence proof that such a thing can be generalized across the needs of multiple protocols..." made me laugh.... I strongly suspect that if you developed such a thing it would look an awful lot like WSDL 2.0.
I think it's clear that we need definitions/descriptions to enable interoperability and lower the barriers to developers.
Now, personally, and to go off on a WSDL based tangent, I think one of the mistakes with WSDL 1.1(BP1.1) is that there's no wildcarding support. There's no way to say 'send me anything' which is what XML centric service developers want to do to start off with, and why they have such painful lives (re)generating schemas etc etc. Even if company policy then mandated that schemas be used when publishing to customers, the barriers to the services developers would be much lower than with current WSDL.
[link]
From: Pat Cappelaere (Jan 21 2008, at 07:15)
If we were to publish complex resources, how can we then describe those resources?
Atom can be extended to list the entries, but how can the client query the server to get to the metadata and know more about the resource structures?
Would you suggest to extend APP?
Would suggest to take the Google GData route? or something else?
This is very critical for the Open Geospatial Community.
Thanks,
Pat.
[link]
From: Jean-Jacques Dubray (Jan 21 2008, at 08:43)
Tim:
could you explain why in your opinion WSDL "sucks, deeply and totally" or point us to a link where you explain why?
I would have thought by now your language would have become just a bit more reasonable.
I love this kind of arguments:
>> So, we have existence proof that there is at least one useful instance of a service declaration.
in relation to
"boringly proceed with useful logical discussions"
Are you discovering that as soon as a resource is an Information Entity it actually as a service interface?
Or am I missing something?
JJ-
[link]
From: Marcus (Jan 21 2008, at 20:20)
Heh, three years of your life? I know RSS (1.0) had it's problems, but using the 80/20 rule, it suddenly doesn't seem so bad.
Maybe a couple minor improvements would have done the trick? And all the apparent heart-ache that people seem to be complaining about right now from the fights they picked wouldn't have happened?
Three years?! LOL. And now all a tech lead like me will do is use it when it is convenient or appropriate, or just to be compatible. But I'm not going to stretch to fit into APP's uncomfortable spaces for all the stuff that APP really isn't designed for (despite the cries of all the Atom designers begging me to look at everything as a nail to hit tihs hammer with.)
Sorry, this is just crazy and smacks of fanaticism in way too many ways. This isn't a troll, this is looking around at the steady stream of daily articles from people speaking of REST wars, and being waaaaay too concerned with my well being without actually appearing to reasonably discuss both sides.
Did it ever occur to you that maybe *both* Vim and Emacs are good tools for good people? Hell, I know plenty of people who use both daily with great expertise! *Sigh*
[link]
From: Laurent Szyster (Jan 23 2008, at 11:42)
What would that "very application-specific way" be?
Could this way be specified with the defacto protocol applied, the ones most widely implemented in applications and development tools?
Namely: URI, HTTP and JSON.
All I need as a programmer to define web 2.0 services is a mapping from URI and HTTP methods (with a bit of PCRE inside) to a regular JSON pattern specification of each service's input (or null when serving indempotent request).
For instance:
{
"GET /countries": null,
"GET /country/(?<code>[A-Z]{3})": null,
"POST /country": {
"code": "[A-Z]{3}",
"name": "^.+$"
}
}
The obvious benefit for a web programmer is that implementations of URI, HTTP, JSON and PCRE are readily available in all development environment.
The disatvantage of this "very application specific" approach is that you can neither sell a pile of useless sophistication begging for compatibility problems, nor lock in your customers into it for ever after.
[link]
From: Joe Pallas (Jan 29 2008, at 16:49)
I think the too-often overlooked distinction is between service endpoint discovery and service definition discovery. There is no value in dynamic discovery of a service definition, because service definitions always lack meaningful semantics. (This is not a criticism of service definitions per se; anything useful is going to lack machine-readable semantics.)
APP Service documents are about endpoint discovery for services defined elsewhere (APP and Atom). That makes sense. Discovering the definition of a new service doesn't make sense, because you can't do anything with it.
[link]