Web Application Description Language

1 介绍

本规范描述了 Web 应用程序描述语言 (WADL)。WADL 旨在提供基于 HTTP 的 Web 应用程序的机器可处理描述。

1.1 网络应用程序

出于本规范的目的，Web 应用程序被定义为基于 HTTP 的应用程序，其交互适合机器处理。虽然许多现有网站都是基于 HTTP 的应用程序的示例，但其中大量网站需要人类认知功能才能成功、不脆弱地使用。典型的 Web 应用程序：

基于现有的 Web 架构和基础设施

平台和编程语言是否独立

促进应用程序在浏览器之外的重复使用

启用与其他 Web 或桌面应用程序的组合

要求使用期间交换的内容（表示）语义清晰

后一个要求可以通过使用自描述数据格式（例如 XML 或 JSON）来满足。XML 特别适合，因为它允许为应用程序域定义完整的自定义模式，或者使用其扩展点将自定义微格式嵌入到现有模式中。

鉴于上述 Web 应用程序的定义，我们可以看到应用程序的以下方面可以用机器可处理的格式有效地描述：

资源集

类似于显示所提供资源的站点地图。

资源之间的关系

描述资源之间的联系，包括参考和因果关系。

可应用于每种资源的方法

可应用于每个资源的 HTTP 方法、预期的输入和输出及其支持的格式。

资源表示格式

支持的 MIME 类型和正在使用的数据架构。

1.2 用例

当前最先进的Web 应用程序描述是文本文档加上一个或多个数据格式定义，例如XML 模式。虽然完全适合人类消费，但这种级别的描述排除了以下需要更机器友好的描述格式的用例：

应用程序建模和可视化

支持开发用于资源关系以及编排分析和操作的资源建模工具。

代码生成

自动生成存根和骨架代码以及用于操作资源表示的代码。

配置

使用可移植格式配置客户端和服务器。

为各个应用程序和协议提供一个共同的基础来重用甚至扩展也将很有用，而不是各自发明一种新的描述格式。

1.3 WADL 描述示例

下面的示例显示了雅虎新闻搜索应用程序的 WADL 描述。

<?xml version="1.0"?>
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd"
xmlns:tns="urn:yahoo:yn"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:yn="urn:yahoo:yn"
xmlns:ya="urn:yahoo:api"
xmlns="http://wadl.dev.java.net/2009/02">

  <grammars>
    <include 
      href="NewsSearchResponse.xsd"/>
    <include
      href="Error.xsd"/>
  </grammars>

  <resources base="http://api.search.yahoo.com/NewsSearchService/V1/">
    <resource path="newsSearch">
      <method name="GET" id="search">
        <request>
          <param name="appid" type="xsd:string"
            style="query" required="true"/>
          <param name="query" type="xsd:string"
            style="query" required="true"/>  
          <param name="type" style="query" default="all">
            <option value="all"/>
            <option value="any"/>
            <option value="phrase"/>
          </param>
          <param name="results" style="query" type="xsd:int" default="10"/>
          <param name="start" style="query" type="xsd:int" default="1"/>
          <param name="sort" style="query" default="rank">
            <option value="rank"/>
            <option value="date"/>
          </param>
          <param name="language" style="query" type="xsd:string"/> 
        </request>
        <response status="200">
          <representation mediaType="application/xml"
            element="yn:ResultSet"/>
        </response>
        <response status="400">
          <representation mediaType="application/xml" 
            element="ya:Error"/>
        </response>
      </method>
    </resource>
  </resources>
  
</application>

第 2-8 行开始应用程序描述并定义服务描述中其他地方使用的 XML 名称空间。第 9-14 行定义服务使用的 XML 语法，在本例中通过引用包含两个 W3C XML 架构文件。第 16-45 行描述了 Yahoo News Search Web 资源及其支持的 HTTP 方法。第 18-43 行描述“搜索”GET 方法：第 19-36 行描述输入；第 37-42 行描述了可能的输出。

2.描述组件

所有 WADL 元素都具有以下 XML 命名空间名称：

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

本节详细描述 WADL 文档的每个组件。

2.1 交叉引用

WADL 中的几个组件支持对其他组件的引用。注意引用是 URI 引用,而不是 ID 引用,因此同时支持文档内和跨文档的引用。文档内引用使用片段标识符,例如 #someid。跨文档引用使用 URI 来标识文档,并使用片段标识符来标识被引用文档中的组件,例如 somefile.wadl#someid。允许使用绝对 URI 或相对 URI。

2.2 应用

该application元素构成 WADL 描述的根并包含以下内容：

零个或多个doc元素 - 请参阅第 2.3 节。

可选grammars元素 - 请参阅第 2.4 节。

零个或多个resources元素 - 请参阅第 2.5 节。

以下零个或多个：

resource_type元素 - 参见第 2.7 节。

method元素 - 参见第 2.8 节。

representation元素 - 参见第 2.11 节。

param元素——参见第 2.12 节。

2.3 文档

每个 WADL 定义的元素都可以有一个或多个doc可用于记录该元素的子元素。该doc元素具有以下属性：

xml:lang

title定义属性值和元素内容的语言doc。如果一个元素包含多个doc元素，那么它们的xml:lang属性必须具有不同的值。

title

正在记录的元素的简短纯文本描述，该值应该适合用作所包含文档的标题。

该doc元素具有混合内容，并且可能包含文本和零个或多个构成文档正文的子元素。建议子元素是 XHTML[ 2 ] 的文本、列表或表格模块的成员。

2.4 语法

该grammars元素充当 WADL 文档描述的协议执行期间交换数据格式定义的容器。此类定义可以内嵌或通过使用include元素的引用来包含（参见第 2.4.1节）。没有强制规定特定的数据格式定义语言；第 3节和第 4 节分别描述了 RelaxNG 和 W3C XML Schema 与 WADL 的使用。

允许包含特定格式的多个定义：假定这些定义是等效的，并且 WADL 描述的使用者可以自由地在替代方案中进行选择，如果它们支持该功能，甚至可以将它们组合起来。

2.4.1 包括

该include元素允许通过引用包含一个或多个数据格式描述的定义。该href属性为引用的定义提供 URI，其类型为xsd:anyURI。使用该include元素在逻辑上相当于将引用的文档内联到 WADLgrammars元素中。

2.5 Resources

该resources元素充当应用程序提供的资源的容器。元素resources具有base类型属性xsd:anyURI，该属性为每个子资源标识符提供基本 URI。后代resource元素（参见第 2.6 节）描述应用程序提供的资源。

2.6 Resource

元素resource描述一组资源，每个资源都由遵循通用模式的 URI 标识。元素resource具有以下属性：

id

xsd:ID标识元素的类型的可选属性resource。

path

类型的可选属性xsd:string。如果存在，它会提供资源标识符的相对 URI 模板。resource资源的基本 URI 由元素的父元素resource或元素给出resources。

type

一个可选属性，其类型是空格分隔的列表xsd:anyURI。列表中的每个值都是一个交叉引用（请参阅第 2.1 节），它标识一个resource_type元素（请参阅第 2.7 节），该元素定义了资源支持的一组方法。

queryType

定义资源 URI 的查询组件的媒体类型。如果未指定，则默认为“application/x-www-form-urlencoded”，这会导致查询字符串按照 HTML 4.01 的第 17.13 节中指定的格式进行格式化。

一个resource元素包含以下子元素：

零个或多个doc元素 - 请参阅第 2.3 节。

零个或多个param元素（参见第 2.12 节），其属性具有以下值之一style：

template

提供有关嵌入模板参数的附加信息，请参见上文。属性值与嵌入模板参数不匹配的子param元素将被忽略。

matrix

指定矩阵 URI 参数

query

method为资源的所有子元素指定全局 URI 查询参数。不适用于从resource_type指定使用type属性继承的方法。

header

method指定在资源的所有子元素的请求部分中使用的全局 HTTP 标头。不适用于从resource_type指定使用type属性继承的方法。

零个或多个method（参见第 2.8 节）元素，每个元素描述可应用于资源的 HTTP 协议方法的输入和输出。这种本地定义的方法被添加到resource_type使用该type属性引用的元素中包含的任何方法中。

零个或多个resource描述子资源的元素。此类子资源从父资源继承矩阵和模板参数，因为它们的 URI 相对于父资源的 URI，但它们不继承为父资源全局指定的查询或标头参数。

属性的值path可以是静态的，也可以包含嵌入的模板参数。在运行时，当使用资源时，模板参数的值会被替换为资源标识符，详细示例请参见第 2.6.1节。

关于嵌入模板参数的附加信息可以使用具有属性值“template”的子param元素来传达，该子元素的属性值与模板中嵌入的参数的名称相匹配。例如，下面的模板参数的类型由子元素指定：style``name``widgetId``param

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

2.6.1 生成资源标识符

元素的 URIresource是使用以下规则获取的：

设置identifier等于为父元素（resource或resources）计算的 URI（使用此过程）。

如果identifier不以“/”结尾，则附加一个“/”字符identifier。

将任何 URI 模板参数的值替换为属性的path值。

将上一步获得的值追加到identifier。

按文档顺序,对每个具有“matrix” style属性值的子param元素(参见2.12节),按以下规则将参数值表示附加到标识符上:

非布尔矩阵参数表示为：';' name'='value

布尔矩阵参数表示为：';' name(当value为true时)。当value为false时,从标识符中省略。

其中name是param元素的name属性的值,value是参数的运行时值

以下示例说明了这些规则并显示了提供多个资源的 Web 应用程序描述的摘录：

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>

上面描述了以下资源：

由静态 URI 标识的资源：http://example.com/widgets

由静态 URI 标识的资源：http://example.com/widgets/reports/stock

由矩阵 URI 标识的资源：http://example.com/widgets/reports/stock;instockonly

由生成 URI 标识的多个资源： http://example.com/widgets/ widgetId，其中URI 的widgetId组件在运行时替换为名为的运行时参数的值。

由生成 URI 标识的多个资源： http://example.com/accounts/ accountId，其中URI 的accountId组件在运行时替换为名为的运行时参数的值。

2.7 资源类型

元素resource_type描述了一组方法，这些方法共同定义了一类资源的行为。resource_type可用于定义预期由多个资源支持的资源行为。

元素resource_type具有以下属性：

id

xsd:ID标识元素的类型的必需属性resource_type。

一个resource_type元素包含以下子元素：

零个或多个doc元素 - 请参阅第 2.3 节。

零个或多个param元素（参见第 2.12 节），其属性具有以下值之一style：

query

为资源类型的所有子元素指定 URI 查询参数。

header

指定在资源类型的所有子元素的请求部分中使用的 HTTP 标头。

零个或多个method（参见第 2.8 节）元素，每个元素都描述可以应用于该类型资源的 HTTP 协议方法。

零个或多个resource描述此类资源的子资源的元素。path此类子资源的 URI 由元素的属性提供resource，并且相对于父资源的 URI。

2.8 方法

元素method描述可应用于资源的HTTP协议方法的输入和输出。元素method可以是方法定义，也可以是对其他地方定义的方法的引用。

2.8.1 方法参考

引用元素是具有类型为的属性的元素method的子元素。属性的值是对定义元素的交叉引用（参见第2.1节）。引用元素不得具有任何其他 WADL 定义的属性或包含任何 WADL 定义的子元素。

method当相同的方法应用于多个资源时，可以使用这种形式的元素来减少重复。

2.8.2 方法定义

方法定义元素是资源或应用程序元素的子元素,具有以下属性:

name

指示使用的 HTTP 方法。

id

方法的标识符，全局定义的方法需要，本地嵌入的方法不允许。方法由 XML ID 标识，并使用 URI 引用来引用。

对于给定资源，允许有多个method具有相同属性值的子元素；name这些同级代表同一 HTTP 方法的不同变体，并且通常具有不同的输入数据。

一个method元素具有以下子元素：

doc

零个或多个doc元素 - 请参阅第 2.3 节。

request

将方法的输入描述为参数集合和可选资源表示形式 - 请参阅第 2.9 节。

response

零个或多个response描述方法可能输出的元素 - 请参阅第 2.10 节。

2.9 要求

元素request描述将 HTTP 方法应用于资源时要包含的输入。元素request没有属性，可以包含以下子元素：

零个或多个doc元素 - 请参阅第 2.3 节。

零个或多个representation元素 - 请参阅第 2.11 节。请注意，元素的使用representation仅限于接受请求中的实体正文的 HTTP 方法（例如，PUT 或 POST）。同级representation元素表示逻辑上等效的替代方案，例如，特定资源可能支持特定请求的多个XML语法。

零个或多个param元素（参见第 2.12 节），其属性具有以下值之一style：

query

为适用于此资源的所有方法指定 URI 查询参数，请参阅第 2.9.1 节

header

指定请求中使用的 HTTP 标头

2.9.1 查询参数

资源或请求中带有 style 值为 query 的子 param 元素(参见 2.12 节)表示 HTML 4.01[3] 17.13 节中描述的 URI 查询参数。在调用 HTTP 方法时,查询参数的运行时值作为 URI 查询参数发送。

以下示例显示了具有生成 URI 的资源，该 URI 支持带有两个可选查询参数的单个 HTTP 方法：

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>

如果 widgetId 参数的值是 123456,customerId 参数的值是 cust1234,verbose 参数的值是 true,那么 HTTP GET 将在以下 URI 上执行:

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

2.10 响应

元素response描述对资源执行 HTTP 方法所产生的输出。它具有以下属性：

status

可选地出现在响应上，提供与特定响应关联的 HTTP 状态代码列表。

一个response元素可以包含以下子元素：

零个或多个doc元素（参见第 2.3 节）。

零个或多个representation元素(参见 2.11 节),每个表示元素描述了执行方法可能产生的资源表示。同级表示元素表示逻辑等价的备选方案;可以使用正常的 HTTP 内容协商机制来选择特定的备选方案。

零个或多个 param 元素(参见 2.12 节),它们的 style 属性值为 header,每个元素指定响应的 HTTP 头部详情。

2.11表示

元素representation描述资源状态的表示。元素representation可以是表示定义，也可以是对其他地方定义的表示的引用。

2.11.1 表示参考

表示引用元素可以是一个请求或响应元素的子元素。它有一个类型为 xsd:anyURI 的 href 属性。href 属性的值是一个交叉引用(参见 2.1 节),指向一个表示定义元素。表示引用元素不能有任何其他 WADL 定义的属性,也不能包含任何 WADL 定义的子元素。

当在多个位置使用相同的表示时，这种形式的representation元素可用于减少重复。

2.11.2 表示定义

表示定义元素可以是一个请求、响应或应用程序元素的子元素。它具有以下属性:

id

表示的标识符，全局定义的表示所需，但本地嵌入的表示不允许。表示由 XML ID 标识并使用 URI 引用进行引用。

mediaType

指示表示的媒体类型。媒体范围（例如text/*）是可接受的，并表示支持指定范围内的任何媒体类型。

element

对于基于 XML 的表示，指定根元素的限定名称，如 2.4grammars节中所述 - 请参阅 2.4 节。

profile

类似于 HTML profile属性,给出一个或多个元数据配置文件的位置,以空格分隔。元数据配置文件定义了后代 link 元素的 rel 和 rev 属性的含义(参见2.12.4节)。

除了上面列出的属性之外，representation定义元素还可以有零个或多个子doc元素（请参阅第 2.3 节）和param元素（请参阅第 2.11.3 节）。

2.11.3 表示参数

子param元素（参见第 2.12 节）用于参数化其父representation元素。根据表示的媒体类型，表示参数可以具有两种不同功能之一：

定义表示的内容。对于属性值为“application/x-www-form-urlencoded”或“multipart/form-data”representation的元素mediaType，表示参数定义根据媒体类型格式化的表示内容。这同样适用于其他媒体类型。

向处理者提供有关表示中感兴趣的项目的提示。对于基于 XML 的表示，表示参数可用于通过 XML 来标识感兴趣的项目。表示参数的属性path指示表示中参数值的路径。对于基于 XML 的表示，这是一个 XPath 表达式。

2.12 参数

元素param描述其父元素的参数化组件。元素param可以是参数定义，也可以是对其他地方定义的参数的引用。

2.12.1 参数参考

参数引用元素是一个 param 元素,它有一个 href 属性,其类型是 xsd:anyURI。href 属性的值是对一个 param 定义元素的引用(参见第2.1节)。一个参数引用元素不能有任何其他 WADL 定义的属性或包含任何 WADL 定义的子元素。

param当相同的参数应用于多个父代时，这种形式的元素可用于减少重复。

2.12.2 参数定义

定义param元素描述其父元素的参数化组件，并且可以是resource（参见第 2.6 节）、application（参见第 2.2 节）、request（参见第 2.9 节）、response（参见第 2.10 节）或representation（参见第 2.11 节）元素的子元素。定义param元素具有零个或多doc个子元素（请参阅第 2.3 节）、零个或多option个子元素（请参阅第 2.12.3 节）、一个可选link子元素（请参阅第 2.12.4 节），并具有以下属性：

id

可选标识符，可用于使用 URI 引用来引用参数定义。

name

参数名称为 xsd:NMTOKEN。必需的。

style

指示参数样式，第 25 页的表 1 列出了允许的值并显示了每个值可以使用的上下文。

type

可以选择将参数的类型指示为 XML 限定名称，默认为xsd:string。

default

（可选）提供一个被视为与未指定的参数值相同的值。

path

当父元素是一个representation元素时，此属性可以选择提供表示中参数值的路径。对于 XML 表示，建议使用 XPath 1.0 [4 ]。

required

可选指示参数是否需要存在，默认为 false（不需要参数）。

repeating

可选地指示参数是单值还是可以有多个值，默认为 false（参数是单值）。

fixed

（可选）为参数提供固定值。

请注意，上述属性的某些组合可能并非在所有情况下都有意义。例如，矩阵 URI 参数通常是可选的，因此param具有style“matrix”值和required“true”值的元素可能是不明智的。

值	`param` 的父元素	用法
matrix	资源	指定矩阵 URI 组件。
header	资源、resource_type、请求或响应	指定与 HTTP 请求（资源或请求）或 HTTP 响应（响应）相关的 HTTP 标头
query	资源、资源类型或请求	指定根据 queryType 属性指定的查询组件媒体类型的规则表示的 URI 查询参数。
query	表示	将表示的一个组件指定为根据媒体类型规则格式化的名称值对。通常与媒体类型“application/x-www-form-urlencoded”或“multipart/form-data”一起使用。
template	资源	该参数被表示为参数值的字符串编码，并被替换为资源元素的路径属性的值，如第 2.6.1 节中所述。
plain	表示	根据媒体类型的规则指定格式化为参数值的字符串编码的表示形式的组成部分。

2.12.3 选项

元素option为其父param元素所表示的参数定义一组可能值中的一个。一个option元素具有以下属性：

value

定义父参数的可能值之一的必需属性。

mediaType

如果存在,则表示父参数作为媒体类型选择器用于响应。属性的值是当参数取值为 value 属性给出的值时所期望的媒体类型。

以下示例显示了带有查询参数的资源方法，可用于请求特定的响应格式：

<method name="GET">
  <request>
    <param name="format" style="query">
      <option value="xml" mediaType="application/xml"/>
      <option value="json" mediaType="application/json"/> 
    </param>
    ...
  </request>
  
  <response>
    <representation mediaType="application/xml"/>
    <representation mediaType="application/json"/>
  </response>
</method>

一个option元素可以有零个或多个doc记录值含义的元素。

2.12.4 关联

link用于标识表示中的资源链接。link元素是 param 元素的子元素,其 path 属性标识包含链接 URI 的父表示的部分。

一个link元素包含零个或多个doc元素（参见第 2.3 节）并具有以下属性：

resource_type

可选的交叉引用(参见 2.1 节),指向定义链接标识的资源功能的 resource_type 元素。

rel

一个可选标记,标识链接标识的资源与嵌入链接的资源表示的关系。值受祖先表示元素 profile 属性的值约束。

rev

一个可选标记,标识嵌入链接的资源表示与链接标识的资源的关系。这是 rel 属性标识的关系的反向关系。值受祖先表示元素 profile 属性的值约束。

以下示例显示了基于 XML 的资源表示形式和两个可能的替代 WADL 表示元素：

<!-- 基于 XML 的小部件表示 -->
<w:widget xmlns:w="http://example.com/widgets">
  <w:loc>http://example.com/widgets/110113</w:loc>
  <w:name>一个小部件</w:name>
  <w:description>一个非常有用的小装置。</w:description>
  <w:price currency="USD">19.99</w:price>
  <w:list>http://example.com/widgets</w:list>
</w:widget>

<!-- 不带参数的小部件表示的 WADL 片段 -->  
<representation mediaType="application/xml"  
  element="w:widget"/>
  
<!-- 带参数的小部件表示的 WADL 片段 -->
<representation mediaType="application/xml"
  element="w:widget">
  <param name="location" style="plain"
    type="xsd:anyURI" path="/w:widget/w:loc">
    <link resource_type="#widget" rel="self"/>
  </param>
  <param name="index" style="plain"
    type="xsd:anyURI" path="/w:widget/w:list">
    <link resource_type="#widgets" rel="index" rev="child"/>
  </param>
</representation>

第二个版本标识了小部件表示中的两个链接：

location

小部件资源的 URI。小部件资源由 id 为"widget"的 WADL resource_type 元素描述。

index

充当小部件索引的资源的 URI。索引资源由 id 为"widgets"的 WADL resource_type 元素描述。

2.13 可扩展性

大多数 WADL 定义的元素都可以使用外部命名空间中的元素或属性进行扩展。WADL 处理器可能会忽略它不理解的扩展，并且扩展作者应该在设计扩展时考虑到这一点。

3 将 RelaxNG 与 WADL 结合使用

一个或多个合法的 RelaxNG 模式可以嵌入在WADLgrammars元素内或者可以通过使用元素的引用来包括include。可以使用 RelaxNG 提供的工具（例如rng:include）将多个 RelaxNG 模式组合在单个模式中。所包含的 RelaxNG 语法的默认命名空间是 WADLgrammars元素的默认命名空间。

element元素的属性是representation指使用元素的XML限定名的对应的RelaxNG元素模式。

4 将 W3C XML 架构与 WADL 结合使用

一个或多个合法的 W3C XML 模式可以嵌入到 WADLgrammars元素中，或者可以通过使用include元素的引用来包含。xsd:include可以使用 W3C XML 模式（例如）提供的工具将多个 W3C XML 模式组合在单个模式中。

element元素的属性是representation指使用元素的 XML 限定名称的相应 W3C XML Schema 全局元素声明。

5 WADL 媒体类型

WADL 文档应使用application/vnd.sun.wadl+xml媒体类型并使用.wadl文件扩展名来提供。有关完整详细信息，请参阅 WADL 媒体类型注册 [5 ]。

A其他示例

A.1亚马逊商品搜索

下面是亚马逊商品搜索服务的WADL描述[ 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>

请注意以下事项：

该方法作为对全局定义方法的引用附加到资源，而不是直接嵌入。在这种情况下，除了说明功能之外，无需执行此操作，但这在一种方法可以应用于多个资源的情况下很有用。

许多查询参数被标记为固定值。Amazon API 使用查询参数来识别服务和这些服务中的操作，使用固定属性可用于允许对同一资源描述多个逻辑方法。如果没有以这种方式固定值的能力，Amazon API 看起来就像一个具有许多参数的单一方法。

SearchIndex 和ResponseGroup 参数都有一组可能的值的枚举。在这两种情况下，仅显示可能值的子集，以最大限度地缩短示例的长度。

A2原子发布协议

Atom 发布协议[ 7 ]定义了一组方法来内省、查看和更新 Atom feed 中的条目。通过对特定提要集的已知 URI 执行 HTTP GET 来引导发布协议。响应由媒体类型为 application/atomserv+xml 的 XML 文档组成，用于描述可用的提要。下面显示了这样的示例：

<service xmlns="http://www.w3.org/2007/app"
  xmlns:atom="http://www.w3.org/2005/Atom">

  <workspace>

    <atom:title>主站点</atom:title>

    <collection
        href="http://example.org/blog/main" >

      <atom:title>主站点</atom:title>

    </collection>

    <collection
      href="http://example.org/blog/pic" >

      <atom:title>图片</atom:title>

      <accept>image/*</accept>

    </collection>

  </workspace>

</service>

请注意 Atom 服务文档和 WADL 之间的相似性，两者都描述了一组可以应用于它们的资源和方法。对于 Atom 服务文档，适用的方法是隐式的，因为它们是由 Atom 发布协议定义的。Atom 服务文档还定义了一些特定于协议域的附加元数据（提要标题）。人们可以使用 WADL 复制 Atom 服务文档中的信息，如下所示。

第一步是创建一个 WADL 文档，其中包含与提要、关联表示和资源类型关联的 Atom 协议方法。此操作只需完成一次，因为此文档的内容随后可以由特定于每个站点的 WADL 文档重复使用。

<application xmlns="http://wadl.dev.java.net/2009/02"
  xmlns:app="http://www.w3.org/2007/app"
  xmlns:atom="http://www.w3.org/2005/Atom">

  <grammars>
    <include href="http://www.w3.org/2007/app/app.xsd"/>
  </grammars>

  <resource_type id="entry_feed">
    <method href="#getFeed"/>
    <method href="#addEntryCollectionMember"/>
  </resource>

  <resource_type id="media_feed">
    <method href="#getFeed"/>
    <method href="#addImageCollectionMember"/>
  </resource>

  <resource_type id="entry">
    ...
  </resource_type>

  <representation id="entry" mediaType="application/atom+xml"
    element="atom:entry"/>

  <representation id="feed" mediaType="application/atom+xml"
    element="atom:feed">
    <param name="first_link" style="plain"
      path="/atom:feed/atom:link[@rel='first']">
      <link resource_type="#entry_feed" rel="first"/>
    </representation>
    <param name="next_link" style="plain"
      path="/atom:feed/atom:link[@rel='next']">
      <link resource_type="#entry_feed" rel="next" rev="previous"/>
    </param>
    <param name="prev_link" style="plain"
      path="/atom:feed/atom:link[@rel='previous']">
      <link resource_type="#entry_feed" rel="previous" rev="next"/>
    </param>
    <param name="last_link" style="plain"
      path="/atom:feed/atom:link[@rel='last']">
      <link resource_type="#entry_feed" rel="last"/>
    </param>
  </representation>

  <method name="GET" id="getFeed">
    <response>
      <representation href="#feed"/>
    </response>
  </method>

  <method name="POST" id="addEntryCollectionMember">
    <request>
      <representation href="#entry"/>
    </request>
    <response status="201">
      <param name="location" style="header" type="xsd:anyURI"
        required="true">
        <link resource_type="#entry" rel="self"/>
      </param>
      <representation href="#entry"/>
    </response>
  </method>

  <method name="POST" id="addImageCollectionMember">
    <request>
      <representation mediaType="image/*"/>
    </request>
    <response status="201">
      <param name="location" style="header" type="xsd:anyURI"
        required="true">
        <link resource_type="#entry" rel="self"/>
      </param>
      <representation href="#entry"/>
    </response>
  </method>

</application>

请注意，上述 WADL 并未定义任何具体资源，仅定义了资源类型、方法和表示形式。鉴于前面的文档位于 http://www.w3.org/2007/app.wadl，可以创建 Atom 服务文档的 WADL 替代方案，如下所示：

<application xmlns="http://wadl.dev.java.net/2009/02"
  xmlns:app="http://www.w3.org/2007/app"
  xmlns:atom="http://www.w3.org/2005/Atom">

  <resources base="http://example.org/">
    <resource path="blog/main"
      type="http://www.w3.org/2007/app.wadl#entry_feed">
      <doc title="主站点"/>
    </resource>
    <resource path="blog/pic"
      type="http://www.w3.org/2007/app.wadl#media_feed">
      <doc title="图片"/>
    </resource>
  </resources>
</application>

上面的 WADL文档按照我们之前定义的资源类型描述了以下资源：

http://example.org/blog/main
此资源支持 HTTP GET 来检索 Atom 提要文档，并支持 HTTP POST 来向提要添加新条目。

http://example.org/blog/pic
此资源支持 HTTP GET 来检索 Atom 提要文档，并支持 HTTP POST 来将新图像添加到提要中。

乙 WADL 的 RelaxNG 架构

可以在此链接找到 WADL 词汇表的规范 RelaxNG 模式。

C WADL 的 XML 架构

可以在此链接中找到 WADL 词汇表的规范 XML 模式。

1 介绍#

1.1 网络应用程序#

1.2 用例#

1.3 WADL 描述示例#

2.描述 组件#

2.1 交叉引用#

2.2 应用#

2.3 文档#

2.4 语法#

2.4.1 包括#

2.5 Resources#

2.6 Resource#

2.6.1 生成资源标识符#

2.7 资源类型#

2.8 方法#

2.8.1 方法参考#

2.8.2 方法定义#

2.9 要求#

2.9.1 查询参数#

2.10 响应#

2.11表示#

2.11.1 表示参考#

2.11.2 表示定义#

2.11.3 表示参数#

2.12 参数#

2.12.1 参数参考#

2.12.2 参数定义#

2.12.3 选项#

2.12.4 关联#

2.13 可扩展性#

3 将 RelaxNG 与 WADL 结合使用#

4 将 W3C XML 架构与 WADL 结合使用#

5 WADL 媒体类型#

A其他示例#

A.1亚马逊商品搜索#

A2原子发布协议#

乙 WADL 的 RelaxNG 架构#

C WADL 的 XML 架构#

1 介绍

1.1 网络应用程序

1.2 用例

1.3 WADL 描述示例

2.描述组件

2.1 交叉引用

2.2 应用

2.3 文档

2.4 语法

2.4.1 包括

2.5 Resources

2.6 Resource

2.6.1 生成资源标识符

2.7 资源类型

2.8 方法

2.8.1 方法参考

2.8.2 方法定义

2.9 要求

2.9.1 查询参数

2.10 响应

2.11表示

2.11.1 表示参考

2.11.2 表示定义

2.11.3 表示参数

2.12 参数

2.12.1 参数参考

2.12.2 参数定义

2.12.3 选项

2.12.4 关联

2.13 可扩展性

3 将 RelaxNG 与 WADL 结合使用

4 将 W3C XML 架构与 WADL 结合使用

5 WADL 媒体类型

A其他示例

A.1亚马逊商品搜索

A2原子发布协议

乙 WADL 的 RelaxNG 架构

C WADL 的 XML 架构