11. Documenting REST Services: WSDL and WADL

WSDL, a W3C recommendation, is the Web Services Description Language. It is commonly used to spell out in detail the services offered by a SOAP server. While WSDL is flexible in service binding options (for example, services can be offered via SMTP mail servers), it did not originally support HTTP operations other than GET and POST. Since REST services often use other HTTP verbs, such as PUT and DELETE, WSDL was a poor choice for documenting REST services.

With version 2.0, WSDL supports all HTTP verbs and it is now considered to be an acceptable method of documenting REST services.

The second alternative is WADL, the Web Application Description Language. WADL is championed by Sun Microsystems. Like the rest of REST, WADL is lightweight, easier to understand and easier to write than WSDL. In some respects, it is not as flexible as WSDL (no binding to SMTP servers), but it is sufficient for any REST service and much less verbose.

Here is a fragment from a WADL specification, describing Amazon's "Item Search" service:

<method name="GET" id="ItemSearch">
 <request>
  <param name="Service" style="query"
   fixed="AWSECommerceService"/>
  <param name="Version" style="query" fixed="2005-07-26"/>
  <param name="Operation" style="query" fixed="ItemSearch"/>
  <param name="SubscriptionId" style="query"
   type="xsd:string" required="true"/>
  <param name="SearchIndex" style="query"
   type="aws:SearchIndexType" required="true">
    <option value="Books"/>
    <option value="DVD"/>
    <option value="Music"/>
  </param>
  <param name="Keywords" style="query"
   type="aws:KeywordList" required="true"/>
  <param name="ResponseGroup" style="query"
   type="aws:ResponseGroupType" repeating="true">
    <option value="Small"/>
    <option value="Medium"/>
    <option value="Large"/>
    <option value="Images"/>
  </param>
 </request>
 <response>
  <representation mediaType="text/xml"
   element="aws:ItemSearchResponse"/>
 </response>
</method>

As you can see, for format is mostly self-explanatory, and it enriches REST with such goodies as type safety using XML schema types.

Some REST advocates, however, find even the lightweight WADL to be an overkill. And indeed, most REST services are documented by no more than a textual description (a human-readable HTML file).

4 comments:

woccur.com said...

The example WADL link seem broken. On that site you can find this example instead:

css-validator.wadl

Michal Dvořák said...

WSDL is unsuitable for REST services (read last section from http://www.ibm.com/developerworks/webservices/library/ws-rest1/), and WADL is not much better. It is not designed to document REST services, and its actually closer to RPC model.
I dont know why almost everyone ignores, that REST service MUST be hypertext driven (look for keyword HATEOAS).
If you want to build REST service, use AtomPub, its the only standarized protocol that allows that (except XHTML of course). WADL will only lead you off the road.

Unknown said...

It is possible to interact with a (Jersey framework) RESTfull service through WADL from PHP ??

Pierre Thierry said...

Neither WSDL nor WADL can describe a REST API, because they can't describe HATEOAS, which is an core constraint of REST.