REST Service 的最佳实践，第 1 部分 重新解析 REST Service-5

look_w

一个定义良好的 RESTful Web 服务接口首先，用一个文档描述 web 服务的 capabilities 以及服务的 location。如清单 15 所示。
清单 15. 用 APP 协议描述的服务 capabilities 和 location

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

<?xml version="1.0" encoding="UTF-8"?> <service xmlns="http://www.w3.org/2007/app"   xmlns:atom="http://www.w3.org/2005/Atom"> <workspace> <atom:title type="text"> InfoSphere MashupHub </atom:title> <collection href="http://localhost:8080/mashuphub/atom?collection=all"> <atom:title type="text"> All </atom:title> <accept> application/atom+xml; type=entry </accept> <categories> <categories> ALL </categories> </categories> </collection> <collection href="http://localhost:8080/mashuphub/atom?collection=feeds"> <atom:title type="text">Feeds</atom:title> <accept> application/atom+xml;type=entry </accept> <categories> <categories> feeds </categories> </categories> </collection> … </workspace> </service>

这个服务文档指明 InfoSphere MashupHub 提供了一系列的 web 服务，包括 list 所有的资源，list 所有的 feeds 等等。并且还描述了每个 web 服务的 location 可以提供的 resource representation 的类型。这种描述文档对于 web 服务的客户端来说非常有益。这个服务描述文档本身也是一个 resource，可以用 HTTP URI 定位到。
其次，我们来看一下每个 web 服务是怎么定义的。
清单 16. RESTful web 服务接口的定义示例

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

1) Resource：所有的 feeds 2) Resource URI： http://localhost:8080/mashuphub/atom?collection=feeds 3) Resource representation：             <feed xmlns="http://www.w3.org/2005/Atom"> <id> http://9.186.64.113:8080/mashuphub/atom?collection=feed </id> <link href="http://9.186.64.113:8080/mashuphub/atom?collection=feeds" rel ="self"></link> <updated> 2010-09-11 T 15:12:24.968Z </updated> <title type = "text"> feeds Collection </title> <author>    <name> InfoSphere MashupHub Search Feed</name> </author> <entry> <author>      <name> InfoSphere MashupHub Search Feed </name>    </author>    <title type="html"> MyCo Customer List </title>    <updated> 2010-09-07 T 05:08:52.000Z </updated>    <id> urn:id:1460 </id> <link href="http://9.186.64.113:8080/mashuphub/atom?collection=feeds&amp;id=1460" rel="self"></link> <link href="http://9.186.64.113:8080/mashuphub/atom?collection=feeds&amp;id=1498" rel="related" title = "MyCo Customer List with weather info" > </link>    <category term="feed"> </category>    <content type = "application/xml" >      <catalog:feed xmlns:catalog="http://www.ibm.com/xmlns/atom/opensearch/feed/1.0/">        <catalog:version> 1.0 </catalog:version>        <catalog:name> MyCo Customer List </catalog:name>        <catalog:author> admin </catalog:author>        <catalog:permission> public </catalog:permission>        <catalog:description> </catalog:description>        <catalog:rating> 0.0 </catalog:rating>        <catalog:useCount> 320 </catalog:useCount>        <catalog:dateModified> 1283836132 </catalog:dateModified>        <catalog:numComments> 0 </catalog:numComments>        <catalog:tags> </catalog:tags>    <catalog:categories> </catalog:categories>                      <catalog:downloadURL>http://9.186.64.113:8080/mashuphub/client    /plugin/generate/entryid/1460/pluginid/3     </catalog:downloadURL>        <catalog:mimetype> application/atom+xml </catalog:mimetype>      </catalog:feed>    </content>      </entry> </feed> 4) Http method: GET 5) 和别的 resource 的关系。 在 representation 中用 <link> 定义了“MyCo Customer List”和“MyCo Customer List with weather info”的关系

总结一下，一个设计良好的 RESTful web 服务应该包括一下几个定义：

• 1)  服务描述文档，如清单 15 所示；
• 2)  资源 (resource) 及其 identification；
• 3)  资源的 representation 的定义
• 4) 用 HTTP method 表示的资源的 manipulation
• 5) 在资源的 representation 里面以 Hyperlink 表述的资源和资源之间的关系

结束语REST 是一种架构风格，汲取了 WWW 的成功经验：无状态，以资源为中心，充分利用 HTTP 协议和 URI 协议，提供统一的接口定义，使得它作为一种设计 Web 服务的方法而变得流行。在某种意义上，通过强调 URI 和 HTTP 等早期 Internet 标准，REST 是对大型应用程序服务器时代之前的 Web 方式的回归。
本文根据 Roy 的论文，结合实际的例子，重新解析了 REST 中的核心概念。根据作者多年的创建和使用 RESTful web 服务的经验，更多的是在观念上的澄清。最后通过一个 RESTful web 服务，告诉读者一个真正意义上的 RESTful web 服务是什么样子。但愿本文的讨论会您提供了一定意义上的思想上的指导和实践上的指导。