Last week there was a bunch of discussion in a number of blogs about whether we need an interface definition language (IDL) for RESTful Web services. There were a lot of good posts on this topic but the posts from Don Box and Bobby Woolf which gave me the most food for thought.

In his post entitled WADL, WSDL, XSD, and the Web Don Box wrote

More interesting fodder on Stefan Tilkov's blog, this time on whether RESTafarians need WSDL-like functionality, potentially in the form of WADL.

Several points come to mind.

First, I'm doubtful that WADL will be substantially better than WSDL given the reliance on XSD to describe XML payloads. Yes, some of the cruft WSDL introduces goes away, but that cruft wasn't where the interop probems were lurking.

I have to concur with Don's analysis about XSD being the main cause of interoperability problems in SOAP/WS-* Web services. In a past life, I was the Program Manager responsible for Microsoft's implementations of the W3C's XML Schema Definition Language (aka XSD). The main problem with the technology is that XML developers wanted two fairly different things from a schema language

1. A grammar for describing and enforcing the contract between producers and consumers of XML documents so that one could, for example, confirm that an XML document received was a valid purchase order or RSS feed.
2. A way describe strongly typed data such as database tables or serialized objects as XML documents for use in distributed programming or distributed query operations.

In hindsight, this probably should have been two separate efforts. Instead the W3C XML Schema working group tried to satisfy both sets of consistuencies with a single XML schema language.  The resulting technology ended up being ill suited at both tasks.  The limitations placed on it by having to be a type system made it unable to describe common constructs in XML formats such as being able to have elements show up in any order (e.g. in an RSS feed title, description, pubDate, etc. can appear in any order as children of item) or being able to specify co-occurrence constraints (e.g. in an Atom feed a text construct may have XML content or textual content depending on the value of its type attribute).

As a mechanism for describing serialized objects for use in distributed computing scenarios (aka Web services) it caused several interoperability problems due to the impedance mismatch between W3C XML Schema and object oriented programming constructs. The W3C XML schema language had a number of type system constructs such as simple type facet restriction, anonymous types, structural subtyping, namespace based wildcards, identity constraints, and mixed content which simply do not exist in the typical programming language. This lead to interoperability problems because each SOAP stack had its own idiosyncratic way of mapping the various XSD type system constructs to objects in the target platform's programming language and vice versa. Also no two SOAP stacks supported the same set of XSD features. Even within Microsoft, let alone across the industry. There are several SOAP interoperability horror stories on the Web such as the reports from Nelson Minar on Google's problems using SOAP in posts such as Why SOAP Sucks and his ETech 2005 presentation Building a New Web Service at Google. For a while, the major vendors in the SOAP/WS-* space tried to tackle this problem by forming a WS-I XML Schema Profile working group but I don't think that went anywhere primarily because each vendor supported different subsets of XSD so no one could agree on what features to keep and what to leave out.

To cut a long story short, any technology that takes a dependency on XSD is built on a shaky technological foundation. According to the WADL specification there is no requirement that a particular XML schema language is used so it doesn't have to depend on XSD. However besides XSD, there actually isn't any mainstream technology for describing serialized objects as XML. So one has to be invented. There is a good description of what this schema language should look like in James Clark's post Do we need a new kind of schema language? If anyone can fix this problem, it's James Clark.

Ignoring the fact that 80% of the functionality of WADL currently doesn't exist because we either need to use a broken technology (i.e. XSD) or wait for James Clark to finish inventing Type Expressions for Data Interchange (TEDI). What else is wrong with WADL?

In a post entitled WADL: Declared Interfaces for REST? Bobby Woolf writes

Now, in typing rest, my colleague Patrick Mueller contemplates that he "wants some typing [i.e. contracts] in the REST world" and, among other things, discusses WADL (Web Application Description Language). Sadly, he's already gotten some backlash, which he's responded to in not doing REST. So I (and Richard, and others?) think that the major advantage of WSDL over REST is the declared interface. Now some of the REST guys seem to be coming around to this way of thinking and are thinking about declared interfaces for REST. I then wonder if and how REST with declared interfaces would be significantly different from WSDL (w/SOAP).

One thing I've learned about the SOAP/WS-* developer world is that people often pay lip service to certain words even though they use them all the time. For example, the technologies are often called Web services even though the key focus of all the major vendors and customers in this area is reinventing CORBA/DCOM with XML protocols as opposed to building services on the Web. Another word that is often abused in the SOAP/WS-* world is contract. When I think of a contract, I think of some lengthy document drafted by a lawyer that spells out in excruciating detail how two parties interact and what their responsibilities are. When a SOAP/WS-* developer uses the word contract and WSDL interchangeably, this seems incorrect because a WSDL is simply the XML version of OMG IDL. And an IDL is simply a list of API signatures. It doesn't describe expected message exchange patterns, required authentication methods, message traffic limits, quality of service guarantees, or even pre and post conditions for the various method calls. You usually find this information in the documentation and/or in the actual business contract one signed with the Web service provider. A WADL document for the REST Web service will not change this fact.

When a SOAP/WS-* says that he wants a contract, he really means he wants an interface definition language (IDL) so he can point some tool at a URL and get some stubs & skeletons automatically generated. Since this post is already long enough and I have to get to work, it is left as an exercise for the reader as to whether a technological approach borrowed from distributed object technologies like DCE/RPC, DCOM and CORBA meshes with the resource oriented, document-centric and loosely coupled world of RESTful Web services.

PS: Before any of the SOAP/WS-* wonks points this out, I realize that what I've described as a contract can in theory be implemented for SOAP/WS-* based services using a combination of WSDL 2.0 and WS-Policy. Good luck actually finding an implementation in practice that (i) works and (ii) is interoperable across multiple vendor SOAP stacks.