一起来学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文件)。

你可能感兴趣的:(REST,application,query,文档,SOAP,邮件服务器)