Skip to main content

Introducing WADL

Posted by mhadley on May 13, 2005 at 2:16 PM PDT

Seems like lots of folks are either doing it or talking about it (publishing proposals for alternatives to WSDL that is) so here's mine: Web Application Description Language (PDF) or WADL for short.

A number of Web based enterprises (Google, Yahoo, Amazon, Flickr to name but a few) are developing XML/HTTP based applications/services that provide access to their internal data. Anecdotal evidence suggests there's a lot of simple XML/HTTP integration going on within other companies too. Add to this the recent interest in AJaX and you're left with a need for a simple way to describe such applications and services.

WADL is designed to provide a simple alternative to WSDL for use with XML/HTTP Web applications. To date such applications have been mainly described using a combination of textual description and XML schema, WADL aims to provide a machine process-able description of such applications in a simpler format than is possible using WSDL.

Here's an example WADL description of the Yahoo news search application to illustrate the language:

01 <?xml version="1.0" standalone="yes"?>
02 <application targetNamespace="urn:yahoo:yn"
03  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
04  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
05  xmlns:yn="urn:yahoo:yn"
06  xmlns:tns="urn:yahoo:yn"
07  xmlns:ya="urn:yahoo:api"
08  xmlns="http://research.sun.com/wadl">
09   
10  <types>
11    <include
12      href="http://.../NewsSearchService/V1/NewsSearchResponse.xsd"/>
13    <include
14      href="http://.../Api/V1/error.xsd"/>
15  </types>
16   
17  <resources>
18    <resource uri="http://.../NewsSearchService/V1/newsSearch">
19      <operationRef ref="tns:NewsSearch"/>
20    </resource>
21  </resources>
22   
23  <operation name="NewsSearch" method="get">
24    <request>
25      <parameter name="appid" type="xsd:string" required="true"/>
26      <parameter name="query" type="xsd:string" required="true"/>
27      <parameter name="type" type="xsd:string"/>
28      <parameter name="results" type="xsd:int"/>
29      <parameter name="start" type="xsd:int"/>
30      <parameter name="sort" type="xsd:string"/>
31      <parameter name="language" type="xsd:string"/>
32    </request>
33    <response>
34      <representation mediaType="text/xml" element="yn:ResultSet">
35        <parameter name="totalResults"
36          type="xsd:nonNegativeInteger"
37          path="/ResultSet/@totalResultsAvailable"/>
38        <parameter name="resultsReturned"
39          type="xsd:nonNegativeInteger"
40          path="/ResultSet/@totalResultsReturned"/>
41        <parameter name="resultPosition"
42          type="xsd:nonNegativeInteger"
43          path="/ResultSet/@firstResultPosition"/>
44        <parameter name="results" path="/ResultSet/Result"/>
45      </representation>
46      <fault name="SearchError" status="400"
47        mediaType="text/xml" element="ya:Error">
48        <parameter name="msg" path="/Error/Message"
49          type="xsd:string"/>
50      </fault>
51    </response>
52  </operation>
53</application>

Lines 2-8 begin an application description and define the XML namespaces used elsewhere in the service description. Lines 10-15 define the XML schemas used by the service, in this case two schemas are included by reference. Lines 17-21 describe the Yahoo News Search Web resource and the operations it supports. Lines 23-52 describe the NewsSearch operation: lines 24-32 describe the inputs to the operation; lines 33-51 describe the possible outputs of the operation.

The WADL specification (PDF) and WADL schema describe the features of the language in detail but a few points are worth highlighting:

  • Generative URIs are handled by including support for parameterization of URI components.
  • The base set of HTTP methods (GET, POST, PUT, DELETE, HEAD) are specifically supported by the WADL schema but the method enumeration is open to use with other methods such as those specified by WebDAV.
  • Representation parameters are hints to processors that point out interesting parts of a resource representation. As such they may be used or ignored as desired. I think they'll be useful for RPC-like interactions but less so for more document oriented work.
  • Sibling representation elements represent alternative representations of the same resource. This means you can describe a resource that is offered in alternate formats, e.g. XML or HTML.
  • The design center is XML/HTTP but this doesn't preclude use with alternate representation formats: the representation/@mediaType attribute provides the necessary hook.

I'm currently working on a WADL to Java compiler and will report back as things progress.

Related Topics >>

Comments

About POST request with files

Great post, very useful. However, I have managed to create a WADL for a RESTful web service (had to create it 'manually'), however one of the sub-services includes receiving a file but I have not found enough information on the W3C site on how to include this information into the WADL file. I'm guessing a file attachment tag or something similar. Do you have any insight on this? Thanks in advance!

 Please post any questions to

 Please post any questions to users@wadl.dev.java.net.