Back to Article List

Originally published July 2007 [ Publisher Link ]

WADL: The REST answer to WSDL

Web service developers were stirred a few months ago in the technical media over the SOAP vs. REST debate, a now familiar theme which seems to come up every so often and one discussion which will surely never be completely settled given that each approach has its own technical merits on which to stand. But appropriate as each technique is for certain circumstances, until recently, there was one obvious part missing in RESTful approaches that was ever present in SOAP: the concept of a descriptor. Up next, we will explore an up and coming proposal named Web Application Description Language (WADL), which aims to provide descriptors for RESTful services.

For SOAP Web services, descriptors based on Web Services Description Language (WSDL) form a fundamental piece of their actual design, mainly on account of the underlying complexity present in the actual service. In these scenarios, a descriptor not only serves the purpose of formally describing all the business logic it can fulfill, but it also aides in the creation of helper classes -- often called stubs -- used to build service clients.

Enter WADL, a similar description language to WSDL, but strictly targeting the requirements of RESTful services. REST started of simple enough, as live URL's on major portals which returned structured data to querying clients, but as interest has grown in this alternate approach to Web services, so has the scope and size of the business processes it attempts to fulfill, making descriptors a natural addition.

REST services being based on the back of HTTP can have the same methods -- GET, POST, PUT, DELETE, HEAD -- available in this latter protocol. Input parameters on the other hand can also grow to be numerous for complex services, making the use of required, optional and type values a welcomed guide for developers trying to make sense of first time requests. When it comes to response values, structure responses have also grown in complexity, ranging from custom XML namespaces to JSON, no to mention the handling of fault scenarios in case a request is aborted.

With that said, lets take a look at a WADL descriptor.

<?xml version="1.0"?>
<application xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:yn="urn:yahoo:yn"
  xmlns:ya="urn:yahoo:api"
  xmlns="http://research.sun.com/wadl">
 
  <grammars>
    <include href="NewsSearchResponse.xsd"/>

    <include href="NewsSearchError.xsd"/>
  </grammars>
  
  <resources base="http://api.search.yahoo.com/NewsSearchService/V1/">
    <resource uri="newsSearch">
      <method href="#search"/>
    </resource>

  </resources>
    
  <method name="GET" id="search">
    <request>
      <query_variable name="appid" type="xsd:string" required="true"/>
      <query_variable name="query" type="xsd:string" required="true"/>
      <query_variable name="type" type="xsd:string"/>

      <query_variable name="results" type="xsd:int"/>
      <query_variable name="start" type="xsd:int"/>
      <query_variable name="sort" type="xsd:string"/>
      <query_variable name="language" type="xsd:string"/>
    </request>
    <response>

      <representation mediaType="application/xml" element="yn:ResultSet"/>
      <fault id="SearchError" status="400" mediaType="application/xml"
        element="ya:Error"/>
    </response>
  </method>

</application>

As you can see, a WADL contract is pretty self descriptive by itself, but there are of course more things you can do with it. One of the most notable actions to take though, is to create stub classes from these WADL contracts to ease the creation of service clients -- an identical process to that of SOAP-based WSDL contracts.

In order to create such service client stubs, an early WADL implementation provided by Sun is equipped with a wadl2java tool, which as its name indicates, takes a WADL contract and creates its corresponding Java stub classes. Executing the following instructions java -jar wadl2java.jar -o gen-src -p com.techtarget.rest http://www.techtarget.com/newsrest.wadl on the previous WADL contract would generate its corresponding Java stubs.

While the mechanics of using such an approach -- that of automated code generation -- have caused criticism among early WADL analysts, stating that its not only unnecessary, but that it will start REST down the same path as SOAP and other distributed technologies like CORBA, which depend on intermediate languages/descriptors, from a practical point of view one cannot deny that using such a contract to obtain stub classes is an even quicker way to get started with REST-based Web services clients.

While WADL is still in its early phases and tools are currently available only for Java environments -- contrary to WSDL, which is more ubiquitous -- WADL's appearance is a vote of confidence in favor of the REST approach to building Web services and will in all likelihood become a tight knit companion when undertaking REST designs in the enterprise, just like WSDL has been one for SOAP.

Originally published July 2007 [ Publisher Link ]

Back to Article List