一起来学REST（11）——REST文档化：WSDL和WADL

   原文地址： http://rest.elkstein.org/

Learn REST: A Tutorial

WSDL（Web Services Description Language，Web服务描述语言）, 是W3C提出的，通常用于SOAP服务器描述其所能提供的服务。WSDL的服务绑定选项灵活（例如，可以通过SMTP邮件服务器提供服务），除了GET和POST之外，并不支持HTTP操作。由于REST服务通常使用HTTP动作，例如PUT和DELETE，所以选择WSDL作为REST服务的文档描述显然不太合适。

在 version 2.0中，WSDL支持所有的HTTP动作，因此目前可以考虑作为REST服务的文档描述。

第二个选择是WADL（Web Application Description Language，Web应用描述语言）。 WADL由Sun公司来主导，同REST类似，WADL是轻量级、易于理解、更易编写。在某些方面，WADL并没有WSDL灵活（没有绑定到SMTP服务），但是但是这对REST来说已经足够了，并且动作更少。

下面是WADL一个片段，描述了亚马逊的“Iten Serch”服务：

<method name="GET" id="ItemSearch">
 <request>
  <param name="Service" style="query"
   fixed="AWSECommerceService"/>
  <param name="Version" style="query" fixed="2005-07-26"/>
  <param name="Operation" style="query" fixed="ItemSearch"/>
  <param name="SubscriptionId" style="query"
   type="xsd:string" required="true"/>
  <param name="SearchIndex" style="query"
   type="aws:SearchIndexType" required="true">
    <option value="Books"/>
    <option value="DVD"/>
    <option value="Music"/>
  </param>
  <param name="Keywords" style="query"
   type="aws:KeywordList" required="true"/>
  <param name="ResponseGroup" style="query"
   type="aws:ResponseGroupType" repeating="true">
    <option value="Small"/>
    <option value="Medium"/>
    <option value="Large"/>
    <option value="Images"/>
  </param>
 </request>
 <response>
  <representation mediaType="text/xml"
   element="aws:ItemSearchResponse"/>
 </response>
</method>

正如所看到的，格式大多数是不明而喻的，类型安全的XMLSchema类型丰富了REST。

• 整个文档的长度仅比上边的代码片段多10行左右（包括XML命名规范、引用Schema语法等），可以在WADL规范中看到
• 点击W3C Unicorn项目规范可以看到一个CSS验证器服务的WADL文档.

Some REST advocates, however, find even the lightweight WADL to be an overkill. And indeed, most REST services are documented by no more than a textual description (a human-readable HTML file).

一些REST的拥护者发现轻量级WADL已经足够，实际上，大多数REST服务文档都是文本描述（人可读的HTML文件）。