W3C W3C Member Submission

Web Application Description Language

W3C Member Submission 31 August 2009

This version:
http://www.w3.org/submissions/2009/SUBM-wadl-20090831/
Latest version:
http://www.w3.org/submissions/wadl/
Authors:
Marc Hadley - Sun Microsystems, Inc

This document is available under the W3C Document License. See the W3C Intellectual Rights Notice and Legal Disclaimers for additional information.


Abstract

This specification describes the Web Application Description Language (WADL). An increasing number of Web-based enterprises (Google, Yahoo, Amazon, Flickr to name but a few) are developing HTTP-based applications that provide programatic access to their internal data. Typically these applications are described using textual documentation that is sometimes supplemented with more formal specifications such as XML schema for XML-based data formats. WADL is designed to provide a machine process-able description of such HTTP-based Web applications.


Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications can be found in the W3C technical reports index at http://www.w3.org/TR/.

WADL and related specifications are provided as-is and for review and evaluation only. Sun Microsystems makes no warrantees or representations regarding the specifications in any manner whatsoever.

By publishing this document, W3C acknowledges that the Submitting Members have made a formal Submission request to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. A W3C Team Comment has been published in conjunction with this Member Submission. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.


Table of Contents

1 Introduction
 1.1 Web Applications
 1.2 Use Cases
 1.3 Example WADL Description
2 Description Components
 2.1 Cross Referencing
 2.2 Application
 2.3 Documentation
 2.4 Grammars
  2.4.1 Include
 2.5 Resources
 2.6 Resource
  2.6.1 Generating Resource Identifiers
 2.7 Resource Type
 2.8 Method
  2.8.1 Method Reference
  2.8.2 Method Definition
 2.9 Request
  2.9.1 Query Parameters
 2.10 Response
 2.11 Representation
  2.11.1 Representation Reference
  2.11.2 Representation Definition
  2.11.3 Representation Parameters
 2.12 Parameter
  2.12.1 Parameter Reference
  2.12.2 Parameter Definition
  2.12.3 Option
  2.12.4 Link
 2.13 Extensibility
3 Use of RelaxNG with WADL
4 Use of W3C XML Schema with WADL
5 WADL Media Type
A Additional Examples
 A.1 Amazon Item Search
 A.2 Atom Publishing Protocol
B RelaxNG Schema for WADL
C XML Schema for WADL
D Document History
 D.1 Changes since November 2006 Publication

1. Introduction

This specification describes the Web Application Description Language (WADL). WADL is designed to provide a machine process-able description of HTTP-based Web applications.

1.1. Web Applications

For the purposes of this specification, a Web application is defined as a HTTP-based application whose interactions are amenable to machine processing. While many existing Web sites are examples of HTTP-based applications, a large number of those require human cognitive function for successful non-brittle use. Typically Web applications:

The latter requirement can be fulfilled by the use of a self-describing data format such as XML or JSON. XML is particularly suitable since it allows the definition of a complete custom schema for the application domain or the embedding of a custom micro-format in an existing schema using its extensibility points.

Given the above definition of a Web application, one can see that the following aspects of an application could be usefully described in a machine processable format:

Set of resources
Analogous to a site map showing the resources on offer.
Relationships between resources
Describing the links between resources, both referential and causal.
Methods that can be applied to each resource
The HTTP methods that can be applied to each resource, the expected inputs and outputs and their supported formats.
Resource representation formats
The supported MIME types and data schemas in use.

1.2 Use Cases

The current state-of-the-art in Web application description is textual documentation plus one or more data format definitions, e.g. XML schemata. Whilst entirely adequate for human consumption, this level of description precludes the following use cases which require a more machine-friendly description format:

Application Modelling and Visualization
Support for development of resource modelling tools for resource relationship and choreography analysis and manipulation.
Code Generation
Automated generation of stub and skeleton code and code for manipulation of resource representations.
Configuration
Configuration of client and server using a portable format.

It would also be useful to have a common foundation for individual applications and protocols to re-use and perhaps extend rather than each inventing a new description format.

1.3 Example WADL Description

The following listing shows an example of a WADL description for the Yahoo News Search[1] application.

 1 <?xml version="1.0"?> 
 2 <application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 3  xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd" 
 4  xmlns:tns="urn:yahoo:yn" 
 5  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 6  xmlns:yn="urn:yahoo:yn" 
 7  xmlns:ya="urn:yahoo:api" 
 8  xmlns="http://wadl.dev.java.net/2009/02"> 
 9   <grammars> 
10     <include 
11       href="NewsSearchResponse.xsd"/> 
12     <include 
13       href="Error.xsd"/> 
14   </grammars> 
15 
16   <resources base="http://api.search.yahoo.com/NewsSearchService/V1/"> 
17     <resource path="newsSearch"> 
18       <method name="GET" id="search"> 
19         <request> 
20           <param name="appid" type="xsd:string" 
21             style="query" required="true"/> 
22           <param name="query" type="xsd:string" 
23             style="query" required="true"/> 
24           <param name="type" style="query" default="all"> 
25             <option value="all"/> 
26             <option value="any"/> 
27             <option value="phrase"/> 
28           </param> 
29           <param name="results" style="query" type="xsd:int" default="10"/> 
30           <param name="start" style="query" type="xsd:int" default="1"/> 
31           <param name="sort" style="query" default="rank"> 
32             <option value="rank"/> 
33             <option value="date"/> 
34           </param> 
35           <param name="language" style="query" type="xsd:string"/> 
36         </request> 
37         <response status="200"> 
38           <representation mediaType="application/xml" 
39             element="yn:ResultSet"/> 
40         </response> 
41         <response status="400"> 
42           <representation mediaType="application/xml" 
43             element="ya:Error"/> 
44         </response> 
45       </method> 
46     </resource> 
47   </resources> 
48 
49 </application>

Lines 2-8 begin an application description and define the XML namespaces used elsewhere in the service description. Lines 9-14 define the XML grammars used by the service, in this case two W3C XML Schema files are included by reference. Lines 16-45 describe the Yahoo News Search Web resource and the HTTP methods it supports. Lines 18-43 describe the 'search' GET method: lines 19-36 describe the input; lines 37-42 describe the possible outputs.

2. Description Components

All WADL elements have the following XML namespace name:

http://wadl.dev.java.net/2009/02

This section describes each component of a WADL document in detail.

2.1 Cross Referencing

Several WADL components support references to other components. Note that references are URI references, not ID references, and therefore support both intra- and inter-document cross referencing. Intra-document references are made using fragment identifiers, e.g. #someid. Inter-document references are made using a URI to identify the document and a fragment identifier to identify the component within the referenced document, e.g. somefile.wadl#someid. Absolute or relative URIs are allowed.

2.2 Application

The application element forms the root of a WADL description and contains the following:

  1. Zero or more doc elements - see section 2.3.
  2. An optional grammars element - see section 2.4.
  3. Zero or more resources elements - see section 2.5.
  4. Zero or more of the following:

2.3 Documentation

Each WADL-defined element can have one or more child doc elements that can be used to document that element. The doc element has the following attributes:

xml:lang
Defines the language for the title attribute value and the contents of the doc element. If an element contains more than one doc element then they MUST have distinct values for their xml:lang attribute.
title
A short plain text description of the element being documented, the value SHOULD be suitable for use as a title for the contained documentation.

The doc element has mixed content and may contain text and zero or more child elements that form the body of the documentation. It is RECOMMENDED that the child elements be members of the text, list or table modules of XHTML[2].

2.4 Grammars

The grammars element acts as a container for definitions of the format of data exchanged during execution of the protocol described by the WADL document. Such definitions may be included inline or by reference using the include element (see section 2.4.1 ). No particular data format definition language language is mandated; sections 3 and 4 describe use of RelaxNG and W3C XML Schema with WADL, respectively.

It is permissible to include multiple definitions of a particular format: such definitions are assumed to be equivalent and consumers of a WADL description are free to choose amongst the alternatives or even combine them if they support that capability.

2.4.1 Include

The include element allows the definitions of one or more data format descriptions to be included by reference. The href attribute provides a URI for the referenced definitions and is of type xsd:anyURI. Use of the include element is logically equivalent to in-lining the referenced document within the WADL grammars element.

2.5 Resources

The resources element acts as a container for the resources provided by the application. A resources element has a base attribute of type xsd:anyURI that provides the base URI for each child resource identifier. Descendent resource elements (see section 2.6 ) describe the resources provided by the application.

2.6 Resource

A resource element describes a set of resources, each identified by a URI that follows a common pattern. A resource element has the following attributes:

id
An optional attribute of type xsd:ID that identifies the resource element.
path
An optional attribute of type xsd:string. If present, it provides a relative URI template for the identifier of the resource. The resource's base URI is given by the resource element's parent resource or resources element.
type
An optional attribute whose type is a space-separated list of of xsd:anyURI. Each value in the list is a cross reference (see section 2.1 ) that identifies a resource_type element (see section 2.7 ) that defines a set of methods supported by the resource.
queryType
Defines the media type for the query component of the resource URI. Defaults to 'application/x-www-form-urlencoded' if not specified which results in query strings being formatted as specified in section 17.13 of HTML 4.01[3].

A resource element contains the following child elements:

The value of the path attribute may be static or may contain embedded template parameters. At runtime, the values of template parameters are substituted into the resource identifier when the resource is used, see section 2.6.1 for a detailed example.

Additional information about embedded template parameters can be conveyed using a child param element with a style attribute value 'template' whose name attribute value matches the name of the parameter embedded in the template. E.g., in the following the type of the widgetId template parameter is specified by the child param element:

1 <resource path="widgets/{widgetId}">  
2   <param name="widgetId" style="template" type="xsd:int"/>  
3   ...  
4 </resource>

2.6.1 Generating Resource Identifiers

The URI for a resource element is obtained using the following rules:

  1. Set identifier equal to the URI computed (using this process) for the parent element (resource or resources)
  2. If identifier doesn't end with a '/' then append a '/' character to identifier
  3. Substitute the values of any URI template parameters into the value of the path attribute
  4. Append the value obtained in the previous step to identifier
  5. For each child param element (see section 2.12), in document order, that has a value of 'matrix' for its style attribute, append a representation of the parameter value to identifier according to the following rules:

    where name is the value of the param element's name attribute and value is the runtime value of the parameter.

The following example illustrates these rules and shows an extract from a Web application description that provides multiple resources:

 1 <resources base="http://example.com/">  
 2   <resource path="widgets">  
 3     <resource path="reports/stock">  
 4       <param name="instockonly" style="matrix"  
 5         type="xsd:boolean"/>  
 6       ...  
 7     </resource>  
 8     <resource path="{widgetId}">  
 9       ...  
10     </resource>  
11     ...  
12   </resource>  
13   <resource path="accounts/{accountId}">  
14     ...  
15   </resource>  
16 </resources>

The above describes the following resources:

2.7 Resource Type

A resource_type element describes a set of methods that, together, define the behavior of a type of resource. A resource_type may be used to define resource behavior that is expected to be supported by multiple resources.

A resource_type element has the following attributes:

id
A required attribute of type xsd:ID that identifies the resource_type element.

A resource_type element contains the following child elements:

2.8 Method

A method element describes the input to and output from an HTTP protocol method that may be applied to a resource. A method element can either be a method definition or a reference to a method defined elsewhere.

2.8.1 Method Reference

A method reference element is a child of a resource element that has an href attribute whose type is xsd:anyURI. The value of the href attribute is a cross reference (see section 2.1 ) to a method definition element. A method reference element MUST NOT have any other WADL-defined attributes or contain any WADL-defined child elements.

This form of method element may be used to reduce duplication when the same method applies to more than one resource.

2.8.2 Method Definition

A method definition element is a child of a resource or application element and has the following attributes:

name
Indicates the HTTP method used.
id
An identifier for the method, required for globally defined methods, not allowed on locally embedded methods. Methods are identified by an XML ID and are referred to using a URI reference.

It is permissible to have multiple child method elements that have the same value of the name attribute for a given resource; such siblings represent distinct variations of the same HTTP method and will typically have different input data.

A method element has the following child elements:

doc
Zero or more doc elements - see section 2.3 .
request
Describes the input to the method as a collection of parameters and an optional resource representation - see section 2.9 .
response
Zero or more response elements that describe the possible outputs of the method - see section 2.10 .

2.9 Request

A request element describes the input to be included when applying an HTTP method to a resource. A request element has no attributes and may contain the following child elements:

  1. Zero or more doc elements - see section 2.3.
  2. Zero or more representation elements - see section 2.11. Note that use of representation elements is confined to HTTP methods that accept an entity body in the request (e.g., PUT or POST). Sibling representation elements represent logically equivalent alternatives, e.g., a particular resource might support multiple XML grammars for a particular request.
  3. Zero or more param elements (see section 2.12) with one of the following values for their style attribute:
    query
    Specifies a URI query parameter for all methods that apply to this resource, see section 2.9.1
    header
    Specifies a HTTP header for use in the request

2.9.1 Query Parameters

Child param elements (see section 2.12 ) of a resource or request with a style value of 'query' represent URI query parameters as described in section 17.13 of HTML 4.01[3]. The runtime values of query parameters are sent as URI query parameters when the HTTP method is invoked.

The following example shows a resource with a generative URI that supports a single HTTP method with a two optional query parameters:

 1 <resources base="http://example.com/widgets">  
 2   <resource path="{widgetId}">  
 3     <param name="customerId" style="query"/>  
 4     <method name="GET">  
 5       <request>  
 6         <param name="verbose" style="query" type="xsd:boolean"/>  
 7       </request>  
 8       <response>  
 9         ...  
10       </response>  
11     </method>  
12   </resource>  
13 </resources>

If the value of the widgetId parameter is '123456' the value of the customerId parameter is 'cust1234' and the value of the verbose parameter is 'true' then the URI on which the HTTP GET will be performed is:

http://example.com/widgets/123456?customerId=cust1234&verbose=true

2.10 Response

A response element describes the output that results from performing an HTTP method on a resource. It has the following attributes:

status
Optionally present on responses, provides a list of HTTP status codes associated with a particular response.

A response element may contain the following child elements:

2.11 Representation

A representation element describes a representation of a resource's state. A representation element can either be a representation definition or a reference to a representation defined elsewhere.

2.11.1 Representation Reference

A representation reference element can be a child of a request or response element. It has a href attribute of type xsd:anyURI. The value of the href attribute is a cross reference (see section 2.1 ) to a representation definition element. A representation reference element MUST NOT have any other WADL-defined attributes or contain any WADL-defined child elements.

This form of representation element may be used to reduce duplication when the same representation is used in multiple locations.

2.11.2 Representation Definition

A representation definition element can be a child of a request, response or application element. It has the following attributes:

id
An identifier for the representation, required for globally defined representations, not allowed on locally embedded representations. Representations are identified by an XML ID and are referred to using a URI reference.
mediaType
Indicates the media type of the representation. Media ranges (e.g. text/*) are acceptable and indicate that any media type in the specified range is supported.
element
For XML-based representations, specifies the qualified name of the root element as described within the grammars section - see section 2.4 .
profile
Similar to the HTML profile attribute, gives the location of one or more meta data profiles, separated by white space. The meta-data profiles define the meaning of the rel and rev attributes of descendent link elements (see section 2.12.4 ).

In addition to the attributes listed above, a representation definition element can have zero or more child doc elements (see section 2.3 ) and param elements (see section 2.11.3 ).

2.11.3 Representation Parameters

A child param element (see section 2.12 ) is used to parameterize its parent representation element. Representation parameters can have one of two different functions depending on the media type of the representation:

  1. Define the content of the representation. For representation elements with a mediaType attribute whose value is either 'application/x-www-form-urlencoded' or 'multipart/form-data' the representation parameters define the content of the representation which is formatted according to the media type. The same may apply to other media types.
  2. Provide a hint to processors about items of interest within a representation. For XML based representations, representation parameters can be used to identify items of interest with the XML. The path attribute of a representation parameter indicates the path to the value of the parameter within the representation. For XML-based representations this is an XPath expression.

2.12 Parameter

A param element describes a parameterized component of its parent element. A param element can either be a parameter definition or a reference to a parameter defined elsewhere.

2.12.1 Parameter Reference

A param reference element is a param element that has an href attribute whose type is xsd:anyURI. The value of the href attribute is a cross reference (see section 2.1 ) to a param definition element. A param reference element MUST NOT have any other WADL-defined attributes or contain any WADL-defined child elements.

This form of param element may be used to reduce duplication when the same parameter applies to more than one parent.

2.12.2 Parameter Definition

A param definition element describes a parameterized component of its parent element and may be a child of a resource (see section 2.6 ), application (see section 2.2 ), request (see section 2.9 ), response (see section 2.10 ), or a representation (see section 2.11 ) element. A param definition element has zero or more doc child elements (see section 2.3 ), zero or more option child elements (see section 2.12.3 ), an optional link child element (see section 2.12.4 ) and has the following attributes:

id
An optional identifier that may be used to refer to a parameter definition using a URI reference.
name
The name of the parameter as an xsd:NMTOKEN. Required.
style
Indicates the parameter style, table 1 on page 25 lists the allowed values and shows the context(s) in which each value may be used.
type
Optionally indicates the type of the parameter as an XML qualified name, defaults to xsd:string.
default
Optionally provides a value that is considered identical to an unspecified parameter value.
path
When the parent element is a representation element, this attribute optionally provides a path to the value of the parameter within the representation. For XML representations, use of XPath 1.0[4] is recommended.
required
Optionally indicates whether the parameter is required to be present or not, defaults to false (parameter not required).
repeating
Optionally indicates whether the parameter is single valued or may have multiple values, defaults to false (parameter is single valued).
fixed
Optionally provides a fixed value for the parameter.

Note that some combinations of the above attributes might not make sense in all cases. E.g. matrix URI parameters are normally optional so a param element with a style value of 'matrix' and a required value of 'true' might be unwise.

Table 1: Values of style attribute and context for use.
Value Parent Element(s) of param Usage
matrix resource Specifies a matrix URI component.
header resource, resource_type, request or response Specifies a HTTP header that pertains to the HTTP request (resource or request) or HTTP response (response)
query resource, resource_type or request Specifies a URI query parameter represented according to the rules for the query component media type specified by the queryType attribute.
query representation Specifies a component of the representation as a name value pair formatted according to the rules of the media type. Typically used with media type 'application/x-www-form-urlencoded' or 'multipart/form-data'.
template resource The parameter is represented as a string encoding of the parameter value and is substituted into the value of the path attribute of the resource element as described in section 2.6.1.
plain representation Specifies a component of the representation formatted as a string encoding of the parameter value according to the rules of the media type.

2.12.3 Option

An option element defines one of a set of possible values for the parameter represented by its parent param element. An option element has the following attributes:

value
A required attribute that defines one of the possible values of the parent parameter.
mediaType
When present this indicates that the parent parameter acts as a media type selector for responses. The value of the attribute is the media type that is expected when the parameter has the value given in the value attribute.

The following example shows a resource method with a query parameter that may be used to request a particular response format:

 1 <method name="GET">  
 2   <request>  
 3     <param name="format" style="query">  
 4       <option value="xml" mediaType="application/xml"/>  
 5       <option value="json" mediaType="application/json"/>  
 6     </param>  
 7     ...  
 8   </request>  
 9   <response>  
10     <representation mediaType="application/xml"/>  
11     <representation mediaType="application/json"/>  
12   </response>  
13 </method>

An option element may have zero or more doc elements that document the meaning of the value.

2.12.4 Link

A link element is used to identify links to resources within representations. A link element is a child of a param element whose path attribute identifies the portion of its parent representation that contains a link URI.

A link element contains zero or more doc elements (see section 2.3) and has the following attributes:

resource_type
An optional cross reference (see section 2.1) to a resource_type element that defines the capabilities of the resource that the link identifies.
rel
An optional token that identifies the relationship of the resource identified by the link to the resource whose representation the link is embedded in. The value is scoped by the value of the ancestor representation element's profile attribute.
rev
An optional token that identifies the relationship of the resource whose representation the link is embedded in to the resource identified by the link. This is the reverse relationship to that identified by the rel attribute. The value is scoped by the value of the ancestor representation element's profile attribute.

The following example shows an XML-based resource representation and two possible alternative WADL representation elements:

 1 <!-- XML-based representation of a widget -->  
 2 <w:widget xmlns:w="http://example.com/widgets">  
 3   <w:loc>http://example.com/widgets/110113</w:loc>  
 4   <w:name>A Widget</w:name>  
 5   <w:description>A very useful gizmo.</w:description>  
 6   <w:price currency="USD">19.99</w:price>  
 7   <w:list>http://example.com/widgets</w:list>  
 8 </w:widget>  
 9  
10 <!-- WADL fragment describing the widget representation  
11      without parameters-->  
12 <representation mediaType="application/xml"  
13   element="w:widget"/>  
14  
15 <!-- WADL fragment describing the widget representation  
16      with parameters -->  
17 <representation mediaType="application/xml"  
18   element="w:widget">  
19   <param name="location" style="plain"  
20     type="xsd:anyURI" path="/w:widget/w:loc">  
21     <link resource_type="#widget" rel="self"/>  
22   </param>  
23   <param name="index" style="plain"  
24     type="xsd:anyURI" path="/w:widget/w:list">  
25     <link resource_type="#widgets" rel="index" rev="child"/>  
26   </param>  
27 </representation>

The second version identifies two links within a widget representation:

location
The URI of a widget resource. A widget resource is described by the WADL resource_type element whose id is 'widget'.
index
The URI of a resource that acts as an index of widgets. The index resource is described by the WADL resource_type element whose id is 'widgets'.

2.13 Extensibility

Most WADL-defined elements are extensible using either elements or attributes from foreign namespaces. A WADL processor MAY ignore extensions that it does not understand and extension authors should design extensions with this in mind.

3 Use of RelaxNG with WADL

One or more legal RelaxNG schemas may be embedded within a WADL grammars element or may be included by reference using an include element. Multiple RelaxNG schemas may be combined within a single schema using the facilities provided by RelaxNG (e.g., rng:include). The default namespace for an included RelaxNG grammar is the default namespace of the WADL grammars element.

The element attribute of representation element refers to a corresponding RelaxNG element pattern using the XML qualified name of the element.

4 Use of W3C XML Schema with WADL

One or more legal W3C XML Schemas may be embedded within a WADL grammars element or may be included by reference using a include element. Multiple W3C XML Schemas may be combined within a single schema using the facilities provided by W3C XML Schema (e.g., xsd:include).

The element attribute of representation element refers to a corresponding W3C XML Schema global element declaration using the XML qualified name of the element.

5 WADL Media Type

WADL documents should be served using the application/vnd.sun.wadl+xml media type and use a .wadl filename extension. See the WADL media type registration[5] for full details.

A Additional Examples

A.1 Amazon Item Search

The following shows a WADL description of the Amazon item search service[6]:

 1 <application xmlns="http://wadl.dev.java.net/2009/02" 
 2   xmlns:aws="http://webservices.amazon.com/AWSECommerceService/2005-07-26" 
 3   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 4   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 5   xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd"> 
 6 
 7   <grammars> 
 8     <include href="AWSECommerceService.xsd"/> 
 9   </grammars> 
10 
11   <resources base="http://webservices.amazon.com/onca/"> 
12     <resource path="xml"> 
13       <method href="#ItemSearch"/> 
14     </resource> 
15   </resources> 
16 
17   <method name="GET" id="ItemSearch"> 
18     <request> 
19       <param name="Service" style="query" 
20         fixed="AWSECommerceService"/> 
21       <param name="Version" style="query" fixed="2005-07-26"/> 
22       <param name="Operation" style="query" fixed="ItemSearch"/> 
23       <param name="SubscriptionId" style="query" 
24          type="xsd:string" required="true"/> 
25       <param name="SearchIndex" style="query" 
26          type="aws:SearchIndexType" required="true"> 
27          <option value="Books"/> 
28          <option value="DVD"/> 
29          <option value="Music"/> 
30       </param> 
31       <param name="Keywords" style="query" 
32         type="aws:KeywordList" required="true"/> 
33       <param name="ResponseGroup" style="query" 
34         type="aws:ResponseGroupType" repeating="true"> 
35          <option value="Small"/> 
36          <option value="Medium"/> 
37          <option value="Large"/> 
38          <option value="Images"/> 
39       </param> 
40     </request> 
41     <response> 
42       <representation mediaType="text/xml" 
43         element="aws:ItemSearchResponse"/> 
44     </response> 
45   </method> 
46 </application>

Note the following:

A.2 Atom Publishing Protocol

The Atom publishing protocol[7] defines a set of methods to introspect, view and update entries in an Atom feed. The publishing protocol is bootstrapped by performing a HTTP GET on a known URI for a particular set of feeds. The response consists of an XML document, of media type application/atomserv+xml, that describes the available feeds. An example of such is shown below:

 1 <service xmlns="http://www.w3.org/2007/app"  
 2      xmlns:atom="http://www.w3.org/2005/Atom">  
 3   <workspace>  
 4     <atom:title>Main Site</atom:title>  
 5     <collection  
 6         href="http://example.org/blog/main" >  
 7       <atom:title>Main Site</atom:title>  
 8     </collection>  
 9     <collection  
10       href="http://example.org/blog/pic" >  
11       <atom:title>Pictures</atom:title>  
12       <accept>image/*</accept>  
13     </collection>  
14   </workspace>  
15 </service>

Note the similarity between the Atom service document and WADL, both describe a set of resources and methods that may be applied to them. In the case of an Atom service document the applicable methods are implicit as they are defined by the Atom Publishing Protocol. An Atom service document also defines some additional metadata (the feed title) specific to the protocol domain. One could replicate the information in an Atom service document using WADL as follows.

The first step is to create a WADL document that contains the Atom protocol methods associated with feeds, associated representations and resource types. This only needs to be done once since the contents of this document can then be re-used by WADL documents specific to each site.

 1 <application xmlns="http://wadl.dev.java.net/2009/02"  
 2   xmlns:app="http://www.w3.org/2007/app"  
 3   xmlns:atom="http://www.w3.org/2005/Atom">  
 4  
 5   <grammars>  
 6     <include href="http://www.w3.org/2007/app/app.xsd"/>  
 7   </grammars>  
 8  
 9   <resource_type id="entry_feed">  
10     <method href="#getFeed"/>  
11     <method href="#addEntryCollectionMember"/>  
12   </resource>  
13  
14   <resource_type id="media_feed">  
15     <method href="#getFeed"/>  
16     <method href="#addImageCollectionMember"/>  
17   </resource>  
18  
19   <resource_type id="entry">  
20     ...  
21   </resource_type>  
22  
23   <representation id="entry" mediaType="application/atom+xml"  
24     element="atom:entry"/>  
25  
26   <representation id="feed" mediaType="application/atom+xml"  
27     element="atom:feed">  
28     <param name="first_link" style="plain"  
29       path="/atom:feed/atom:link[@rel='first']">  
30       <link resource_type="#entry_feed" rel="first"/>  
31     </representation>  
32     <param name="next_link" style="plain"  
33       path="/atom:feed/atom:link[@rel='next']">  
34       <link resource_type="#entry_feed" rel="next" rev="previous"/>  
35     </param>  
36     <param name="prev_link" style="plain"  
37       path="/atom:feed/atom:link[@rel='previous']">  
38       <link resource_type="#entry_feed" rel="previous" rev="next"/>  
39     </param>  
40     <param name="last_link" style="plain"  
41       path="/atom:feed/atom:link[@rel='last']">  
42       <link resource_type="#entry_feed" rel="last"/>  
43     </param>  
44   </representation>  
45  
46   <method name="GET" id="getFeed">  
47     <response>  
48       <representation href="#feed"/>  
49     </response>  
50   </method>  
51  
52   <method name="POST" id="addEntryCollectionMember">  
53     <request>  
54       <representation href="#entry"/>  
55     </request>  
56     <response status="201">  
57       <param name="location" style="header" type="xsd:anyURI"  
58         required="true">  
59         <link resource_type="#entry" rel="self"/>  
60       </param>  
61       <representation href="#entry"/>  
62     </response>  
63   </method>  
64  
65   <method name="POST" id="addImageCollectionMember">  
66     <request>  
67       <representation mediaType="image/*"/>  
68     </request>  
69     <response status="201">  
70       <param name="location" style="header" type="xsd:anyURI"  
71         required="true">  
72         <link resource_type="#entry" rel="self"/>  
73       </param>  
74       <representation href="#entry"/>  
75     </response>  
76   </method>  
77  
78 </application>

Note that the above WADL doesn't define any concrete resources only resource types, methods and representations. Given the preceding document located at http://www.w3.org/2007/app.wadl, one can create a WADL alternative to the Atom service document as follows:

 1 <application xmlns="http://wadl.dev.java.net/2009/02"  
 2   xmlns:app="http://www.w3.org/2007/app"  
 3   xmlns:atom="http://www.w3.org/2005/Atom">  
 4  
 5   <resources base="http://example.org/">  
 6     <resource path="blog/main"  
 7       type="http://www.w3.org/2007/app.wadl#entry_feed">  
 8       <doc title="Main Site"/>  
 9     </resource>  
10     <resource path="blog/pic"  
11       type="http://www.w3.org/2007/app.wadl#media_feed">  
12       <doc title="Pictures"/>  
13     </resource>  
14   </resources>  
15 </application>

The above WADL document describes the following resources in terms of the resource types we defined earlier:

B RelaxNG Schema for WADL

A normative RelaxNG schema for the WADL vocabulary can be found at this link.

C XML Schema for WADL

A normative XML schema for the WADL vocabulary can be found at this link.

References

[1] Yahoo! Web APIs. Technical report, Yahoo!, 2005. See http://developer.yahoo.net/.

[2] Murray Altheim, Frank Boumphrey, Sam Dooley, Shane McCarron, Sebastian Schnitzenbaumer, and Ted Wugofski. Modularization of XHTML. Recommendation, W3C, April 2001. See http://www.w3.org/TR/xhtml-modularization.

[3] Dave Raggett, Arnaud Le Hors, and Ian Jacobs. HTML 4.01 Specification. Recommendation, W3C, December 1999. See http://www.w3.org/TR/html4/.

[4] James Clark and Steve DeRose. XML Path Language (XPath) 1.0. Recommendation, W3C, November 1999. See http://www.w3.org/TR/xpath.

[5] M. Hadley. The application/vnd.sun.wadl+xml Media Type. Media Type, IANA, March 2006. See http://www.iana.org/assignments/media-types/application/vnd.sun.wadl+xml.

[6] Amazon.com. Amazon Web Services. Technical report, Amazon.com, 2005. See http://www.amazon.com/.

[7] J. Gregorio and B. de hOra. The Atom Publishing Protocol. Internet Draft, IETF, October 2007. See http://www.ietf.org/rfc/rfc5023.txt.

D Document History

This section lists changes to the specification and grammar of WADL for each release. Changes may reference issues which may be viewed in the issue tracker at:

https://wadl.dev.java.net/issues/show_bug.cgi?id=issueNumber

where issueNumber is the number of the issue.

D.1 Changes since November 2006 Publication

Acknowledgments

Thanks to the members of the http://lists.w3.org/Archives/Public/public-web-http-desc/ and http://wadl.dev.java.net/servlets/SummarizeList?listName=users mailing lists who provided useful feedback on several iterations of this specification. Mark Nottingham and John Nienart (Yahoo!) provided extensive feedback and helped structure the overall design.

Copyright Notice

Copyright 2005-2009 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.

Unlimited copying without fee is permitted provided that the copies are not made nor distributed for direct commercial advantage, and credit to the source is given. Otherwise, no part of this work covered by copyright may be reproduced in any form or by any means graphic, electronic, or mechanical, including photocopying, recording, taping, or storage in an information retrieval system, without the prior written permission of the copyright owner.

U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements.

Sun, Sun Microsystems and the Sun logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.