mark nottingham

One Description to Bind them All? Nah.

Friday, 8 July 2005

HTTP APIs Web Services

You can describe just about anything with sufficient precision in plain English, given enough words. In practice, this doesn’t happen; specialised fields — whether science, finance or art — develop specialised jargon as a shorthand for concepts that are well-understood in that field. It gives greater precision, easier flow of ideas, and yes, it raises the bar to entry for newcomers.

The trade-off is worth it, usually; although it would be genuinely useful if a layman could understand the law, efforts in that direction have failed; capturing the nuances of the law in everyday prose is so verbose as to be ridiculous.

Similarly, XML* gives you a lot of rope; it’s just a syntax that you can define a language in; the scope is up to you. If your language is generic, it trades the power of specificity and a tight fit with the use cases for repurposeability.

This brings a choice when you’re developing an XML language (a.k.a. jargon); you either go broad and shallow, or narrow and deep.

Fitting the Description to the Architecture

In the Web Services world, WSDL is a generic protocol description format; it tries to be both broad and deep. It purports to be able to describe different protocols with different architectural styles — e.g., RPC, SOA and REST — equally. Or, at least, people have tried to mold it to do all three at various times.

Forcing the description of all possible protocols is too much to ask of one format; the logistics of developing, standardising and debugging such a thing is a herculean task, and efforts on that scale inevitably lead to failure, or watered-down, least-common-denominator “successes”.

Case in point; WSDL devolves everything to a lot of one-way messages and operations and a few services, because that’s its jargon; while that’s fine for SOA (which is nothing more than messaging) and workable for RPC, it’s totally inappropriate for REST, which works in terms of resources and representations. As a result, WSDL’s operation-centric view of the world makes the description of the multitude of resources that REST favours laborious, at best.

Some people might think “ah, but WSDL offers an abstraction to build other abstractions upon; that’s why it’s so broad.” To which I say, baloney. There is good abstraction and bad, pointless abstraction, and I think we know how much of each kind WSDL embodies.

So, I think that WSDL is too ambitious; the world would be better off if there were separate description formats for separate architectural styles; i.e., we could have a SOA description format, a RPC description format, and a REST description format**.

This is also why I’m interested in Web description as a separate thing from Web services description. The latter should really be called SOA Description, and not try to accommodate REST or even RPC at all; it’s the technically right thing to do, and it makes the REST vs. Web Services politics (which was always a red herring) a lot easier.

* I think a lot of the same issues are faced when minting ontologies on the Semantic Web; for the purposes of this, there aren’t enough differences to warrant the alienated readers…

** That’s not to say that they couldn’t share some common constructs, of course.