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
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:
- Are based on existing Web architecture and infrastructure
- Are platform and programming language independent
- Promote re-use of the application beyond the browser
- Enable composition with other Web or desktop applications
- Require semantic clarity in content (representations) exchanged during their use
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:
- Zero or more
doc elements - see section 2.3.
- An optional
grammars element - see section 2.4.
- Zero or more
resources elements - see section 2.5.
- Zero or more of the following:
resource_type elements - see section 2.7.method elements - see section 2.8.representation elements - see section 2.11.param elements - see section 2.12.
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:
- Zero or more
doc elements - see section 2.3 .
- Zero or more
param elements (see section 2.12 ) with one of the following values for its style attribute:
template- Provides additional information about an embedded template parameter, see above. Child
param elements whose name attribute value does not match the name of an embedded template parameter are ignored.
matrix- Specifies a matrix URI parameter
query- Specifies a global URI query parameter for all child
method elements of the resource. Does not apply to methods inherited from a resource_type specified using the type attribute.
header- Specifies a global HTTP header for use in the request part of all child
method elements of the resource. Does not apply to methods inherited from a resource_type specified using the type attribute.
- Zero or more
method(see section 2.8 ) elements, each of which describes the input to and output from an HTTP protocol method that can be applied to the resource. Such locally-defined methods are added to any methods included in resource_type elements referred to using the type attribute.
- Zero or more
resource elements that describe sub-resources. Such sub-resources inherit matrix and template parameters from the parent resource since their URI is relative to that of the parent resource but they do not inherit query or header parameters specified globally for the parent resource.
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:
- Set
identifier equal to the URI computed (using this process) for the parent element (resource or resources)
- If
identifier doesn't end with a '/' then append a '/' character to identifier
- Substitute the values of any URI template parameters into the value of the
path attribute
- Append the value obtained in the previous step to
identifier
- 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:
- Non-boolean matrix parameters are represented as: ';'
name '=' value
- Boolean matrix parameters are represented as: ';'
name when value is true and are omitted from identifier when value is false
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:
- A resource identified by a static URI: http://example.com/widgets
- A resource identified by a static URI: http://example.com/widgets/reports/stock
- A resource identified by a matrix URI: http://example.com/widgets/reports/stock;instockonly
- Multiple resources identified by generative URIs: http://example.com/widgets/widgetId, where the widgetId component of the URI is replaced at runtime with the value of a runtime parameter called
widgetId.
- Multiple resources identified by generative URIs: http://example.com/accounts/accountId, where the accountId component of the URI is replaced at runtime with the value of a runtime parameter called
accountId.
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:
- Zero or more
doc elements - see section 2.3 .
- Zero or more
param elements (see section 2.12 ) with one of the following values for its style attribute:
query- Specifies a URI query parameter for all child
method elements of the resource type.
header- Specifies a HTTP header for use in the request part of all child
method elements of the resource type.
- Zero or more
method (see section 2.8 ) elements, each of which describes an HTTP protocol method that can be applied to a resource of this type.
- Zero or more
resource elements that describe sub-resources of resources of this type. The URI of such sub-resources is provided by the path attribute of the resource element and is relative to that of the parent resource.
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:
- Zero or more
doc elements - see section 2.3.
- 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.
- 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:
- Zero or more
doc elements (see section 2.3 ).
- Zero or more
representation elements (see section 2.11 ), each of which describes a resource representation that may result from performing the method. Sibling representation elements indicate logically equivalent alternatives; normal HTTP content negotiation mechanisms may be used to select a particular alternative.
- Zero or more
param elements (see section 2.12 ) with a value of 'header' for their style attribute, each of which specifies the details of a HTTP header for the response
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:
- 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.
- 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:
- The method is attached to the resource as a reference to a globally defined method rather than being embedded directly. In this instance there is no need to do this beyond illustrating the capability but this is useful where one method can be applied to multiple resources.
- A number of the query parameters are marked as fixed value. The Amazon API uses query parameters to identify services and operations within those services, use of the fixed attribute can be used to allow description of multiple logical methods on the same resource. Without the ability to fix values in this way, the Amazon API would look like one single method with many parameters.
- The SearchIndex and ResponseGroup parameters both have an enumerated set of possible values. In both cases only a subset of possible values is shown to minimize the length of the example.
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:
http://example.org/blog/main
This resource supports HTTP GET to retrieve an Atom feed document and HTTP POST to add a new entry to the feed.http://example.org/blog/pic
This resource supports HTTP GET to retrieve an Atom feed document and HTTP POST to add a new image to the feed.
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
- The namespace was changed to http://wadl.dev.java.net/2009/02.
- Resolved issue 13. The
status attribute was moved from the representation element to the response element. The cardinality of the response element was changed from 0-1 to 0-many. The fault element was removed.
- Resolved issue 17. Allow parameters at top level and parameter references to prevent repetition when a parameter is used in multiple places.
- Resolved issue 18. A
resource_type element may now contain resource child elements.
- Resolved issue 20. Allow multiple resources elements within an application.
- Updated the Atompub example to RFC syntax.
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.