REST Web 服务的一切——是什么和如何做——第 2 部分——设计

设计 RESTful Web 服务步骤

将拼图的碎片拼凑起来

在我上一篇文章中，我介绍了 REST Web 服务的概念。在急于着手实现或编写 REST Web 服务之前，我们首先需要停在设计阶段。我知道许多开发人员更热衷于在花费一些时间进行proper design之前就开始编码。他们有时会忽略一个事实：你不需要 Visual Studio 来进行设计；白板就足够了。

给定一个 Web 服务需求，REST 设计的第一步是确定我们将要暴露的对象及其各自的表示（representation）。对象的表示可以被认为是其属性的集合。表示需要仔细设计，我们很快就会看到这一点。

让我们尝试基于经典的员工管理示例来构建。想象一个旨在提供员工管理界面的 Web 服务。这是一个好的开始，因为要暴露的对象很容易达成一致——员工。请记住，在 REST 中，我们暴露的是对象而不是方法。

下一步是确定对象的表示——对于我们的示例，一个简单的 XML 结构是否足够？

<Employee id='25648'>
    <Name>Peter Scheufele</Name>
    <Address>123 Main St. Dallas TX 75226</Address>
    <Designation>System Analyst</Designation>
    <HireDate>08/20/2007</HireDate>
</Employee>

在这里，我需要强调几个关于表示真正含义以及如何设计它的重要观点。为了让我能够做到这一点，让我们来研究一下资源（resource）和URI的概念。

在客户服务时代，REST Web 服务最大的推动力在于它应该让客户端更容易使用。如果客户端可以直接在 URL 中输入他们想要操作的对象，那么对客户端来说会变得多么容易？

想象一下，一位人力资源专员想要查看员工 Peter Scheufele 的详细信息——她在浏览器地址栏中输入：

http://employeeinfo/v1.4/employee/12098

她必须知道 12098 是 Peter 的员工 ID。即使她不知道，那么 URL

http://employeeinfo/v1.4/employees?name=peter

并获得一个名字中包含“peter”的员工列表，怎么样？

注意上面两个 URL 中的 **employee** 和 **employees** 这两个词。它们是资源（resources）。资源是 REST Web 服务暴露并使用 URL 本身访问的对象。在这个例子中，Web 服务暴露了两个对象——employee，代表一个员工，以及employees，代表员工的集合。严格来说，这些地址是URI，而不是URL。因为它们比定位资源做得更多，它们实际上是**标识资源**。这就是为什么它们是**统一资源标识符（uniform resource identifiers）**。

资源的表示应该被视为资源的状态。如果表示发生变化，那就是对该资源进行了 UPDATE 操作。表示通常是在响应 GET 请求时返回的。我们将employee对象的表示设为 XML。必须是 XML 吗？不。它可以是任何东西，但 XML 很难被超越。好的 REST Web 服务除了 XML，也支持 JSON，但我们先坚持使用 XML，以便理清基本概念。

回到 HTTP 动词，REST 建立了一个基本指南：Web 服务应该如何响应 HTTP 动词 GET、PUT、POST 和 DELETE？以下是这些指南：

• GET：**返回**（检索）URI 上标识的资源的表示。

示例

客户端 --> 服务器：客户端调用我们的 Web 服务以获取 Peter Scheufele 的详细信息：

GET http://employeeinfo/v1.4/employee/12098 HTTP/1.1
Accept: */*
Accept-Language: en-us
Authorization: hisyi76985==03784j3bkngdfyuwetfiuw
User-Agent: Client Application developed by the super coders
Host: supercoders
Connection: Keep-Alive

服务器 --> 客户端：服务器响应 Peter Scheufele 的表示：

HTTP/1.1 200 Ok
Server: Apache-Coyote/1.1
Last-Modified: Thu, 11 Oct 2007 14:45:35 GMT
ETag: 12098
Location: "http://employeeinfo/v1.4/employee/12098">http://employeeinfo/v1.4/employee/12098 
Date: Fri, 12 Oct 2007 12:00:28 GMT
Connection: Close
Content-Type: text/xml; charset=UTF-8
Content-Length: 2324

<Employee id='12098'>
    <Name>Peter Scheufele</Name>
    <Address>123 Main St. Dallas TX 75226</Address>
    <Designation>System Analyst</Designation>
    <HireDate>08/20/2007</HireDate>
</Employee>

注意：请注意，请求没有 HTTP 主体，但响应包含 Peter Scheufele 的表示作为 HTTP 主体，并且它将一些特定的 HTTP 标头设置为特定值——这些是REST 的最佳实践。

• PUT：**更新** URI 上标识的资源的表示。

示例

客户端 --> 服务器：客户端调用我们的 Web 服务以更新 Peter Scheufele 的地址：

PUT http://employeeinfo/v1.4/employee/12098 HTTP/1.1
Accept: */* 
Accept-Language: en-us
Authorization: hisyi76985==03784j3bkngdfyuwetfiuw
User-Agent: Client Application developed by the super coders
Host: supercoders
Connection: Keep-Alive
Content-Type: text/xml; charset=UTF-8
Content-Length: 354

<Employee id='12098'>
    <Address>6777 Spring Creek Dr. Fairview TX - 56458</Address>
</Employee>

服务器 -->客户端：服务器更新 Peter Scheufele 的地址并响应 Peter Scheufele 的表示：

HTTP/1.1 200 Ok
Server: Apache-Coyote/1.1
Last-Modified: Thu, 11 Oct 2007 14:45:35 GMT
ETag: 12098
Location: "http://employeeinfo/v1.4/employee/12098">http://employeeinfo/v1.4/employee/12098 
Date: Fri, 12 Oct 2007 12:00:28 GMT
Connection: Close
Content-Type: text/xml; charset=UTF-8
Content-Length: 2214

<Employee id='12098'>
    <Name>Peter Scheufele</Name>
    <Address>6777 Spring Creek Dr. Fairview TX - 56458</Address>
    <Designation>System Analyst</Designation>
    <HireDate>08/20/2007</HireDate>
</Employee>

注意：请注意，请求将员工表示 XML 作为 HTTP 主体发送，但有趣的是，它只发送需要更新的信息。这不是任何指南的一部分——这取决于您，Web 服务的设计者，来决定——您是期望客户端在更新时发送整个表示 XML，还是只发送需要更新的元素。一个架构良好的系统通常会使用 XSD 来验证传入的 XML，因此 XML 模式需要设计成允许增量更新 XML。这里我们已经显著偏离了纯粹的 REST 讨论，因为这些讨论是应用程序特定的设计，但我认为这些对于强调 REST 的实际方面是必要的。

请注意，响应会携带 Peter Scheufele 的完整表示，这是 REST 的最佳实践。当资源的表示被更新时，Web 服务应该在成功更新后将完整的表示发回给客户端。同样，这不是一个“不能违反”的规则，只是推荐。

另外两个动词：POST 和 DELETE

既然我们已经看到了 GET 和 PUT 的实际应用，现在是时候处理 POST 了。在深入研究 POST 之前，让我们快速回顾一下上面已经提到的 GET 和 PUT 的定义：

GET：返回（检索）URI 上标识的资源的表示。

PUT：更新 URI 上标识的资源的表示。

注意这两个动词是如何作用于资源的表示的？您是否还记得上一篇文章中解释的 REST 的高层目标？就是用少数标准动词作用于暴露的名词的整个想法？我们在这里看到的正是这样：GET 和 PUT 以一种标准、预定义的方式作用于资源employee/12098：GET 检索它，PUT 更新它。

为了更准确地说，GET 检索了表示，PUT 更新了表示。因此，我们现在对表示有了更清晰的认识：它充当资源的别名——**HTTP 动词实际作用的部分**。

话虽如此，让我们转向 POST。在 REST 中，**POST 意味着创建新资源**。您能想象一个请求作用于某个现有资源的表示吗？怎么可能？

因此，如果客户端对 **http://employeeinfo/v1.4/employee/12098** 执行 POST 操作，是否有意义？显然不是——因为要创建的新资源与 12098（Peter Scheufele）无关。

如果 POST 请求发送到 **http://employeeinfo/v1.4/employee** 呢？嗯——虽然这有点意义，但我们仍然难以强制执行规则——**REST 请求应该作用于 URI 所标识的资源的表示**。首先，这里的 URI 并没有标识任何特定的员工，也没有单独的employee的表示。

这正是集合资源（collection resource）的必要性所在。我们在想象一位人力资源员工摆弄 REST 时，已经简要提到了集合资源。

集合资源有自己的表示，其特点是它不需要任何特定的实例即可访问。让我们为我们的 Web 服务暴露第二个对象：

employees

作为 employee 的复数形式，employees 是一个集合资源，具有以下表示：

<Employees>
    <Employee id='12098'>
        <Name>Peter Scheufele</Name>
        <Address>6777 Spring Creek Dr. Fairview TX - 56458</Address>
        <Designation>System Analyst</Designation>
        <HireDate>08/20/2007</HireDate>
    </Employee>
    <Employee id='58585'>
        <Name>Tina Sreenivas</Name>
        <Address>324 Valley View Rd. Anna TX - 75848</Address>
        <Designation>HR Analyst</Designation>
        <HireDate>01/10/2005</HireDate>
    </Employee>
    <!-- Multiple Employee element supported -->
</Employees> 

不一定非要使用复数作为集合资源的名称——我们可以称之为EmployeesColl或AllEmployees或其他任何名称。此外，如果每个employee的单独表示过于庞大，将每个employee的完整表示打包到employees中可能会不切实际且性能下降。在这种情况下，我们可以定义employees的表示如下：

<Employees>
    <Employee id='12098'>
    "http://employeeinfo/v1.4/employee/12098">http://employeeinfo/v1.4/employee/12098
    </Employee>
    <Employee id='58585'>
    http://employeeinfo/v1.4/employee/58585
    </Employee>
    <!-- Multiple Employee element supported -->
</Employees>

此表示仅打包集合中每个员工的 URI，而不是每个员工的完整表示。然后，客户端需要为每个员工发出 GET 命令（在其各自的 URI 上）以获取单独的数据。

请注意，暴露的employees对象不需要指定任何特定的员工 ID——因此，它可以被视为一个全局资源。如果客户端对 employees 执行 GET 操作，它将如下所示：

GET http://employeeinfo/v1.4/employees HTTP/1.1

响应将包含employees的完整表示，其中包含所有员工。

在 REST 中，您还可以定义自己的查询字符串参数。您可以使用 GET 和employees资源组合来暴露一个**搜索**功能。例如，您可以支持查询字符串参数**name**和**address**。作为响应，您返回的表示 XML 可能只包含满足搜索条件的那些员工。例如：

GET http://employeeinfo/v1.4/employees?name='george' HTTP/1.1

上面的请求将返回名字中包含“george”的所有员工的列表。

突然，一系列新的无限可能性出现了——不是吗？通过您定义的资源、您设计的表示以及您设计的查询字符串参数的巧妙组合——世界尽在您的掌握！虽然传统的 Web 服务的方法提供了一种单调乏味的单边暴露您功能的维度——REST 为您提供了一系列有趣的组件，可以组合成令人眼花缭乱的服务——所有这些都在标准化的 HTTP 动词及其标准含义的框架内。

对此感到兴奋吗？让我们回到 POST。您可能已经猜到了——在我们的示例中，POST 动词应该只允许在employees资源上使用。

因此，请求：

POST http://employeeinfo/v1.4/employees HTTP/1.1

<Employee id=''>
    <Name>Bruce Evans</Name>
    <Address>1 ABC Rd. OK - 85748</Address>
    <Designation>Assistant Manager</Designation>
    <HireDate>11/12/2007</HireDate>
</Employee>

正在请求创建一个新员工——Bruce Evans。请注意，这如何遵循 REST 指南——**REST 请求应该作用于 URI 所标识的资源的表示**。我们是否遵循了这项指南？一字不差！看它是如何做的：这个 URI 中标识的资源是什么？Employees。它的表示是什么？包含所有employee元素的 XML。此请求**作用于该表示**，因为它在末尾创建了另一个employee节点。

关于此 POST 请求需要注意的几点：它不在请求 XML 中发送员工 ID，因为新员工尚未创建。它必须提供足够的信息，以便服务能够创建新员工。响应可以返回包含新创建的员工的employees的表示，或者可以返回新创建的employee的表示。响应应包含新员工的 ID。响应应携带 HTTP 响应代码 201 Created（而不是 200 Ok）。

DELETE 动词用于删除资源。现在我们有两个资源：employee和employees，DELETE 可以作用于其中任何一个，但要作用于employees，它必须指定要删除哪个员工，这可以通过查询字符串**id**来完成。因此：

DELETE http://employeeinfo/v1.4/employees?id=45125 HTTP/1.1

DELETE http://employeeinfo/v1.4/employee/45125 HTTP/1.1

POST http://employeeinfo/v1.4/employee HTTP/1.1

<Employee id=''>
    <Name>Bruce Evans</Name>
    <Address>1 ABC Rd. OK - 85748</Address>
    <Designation>Assistant Manager</Designation>
    <HireDate>11/12/2007</HireDate>
</Employee>

POST http://mybank.loans.com/v2.0/loanapplication HTTP/1.1
<application>
    …
</application>

GET http://mybank.loans.com/v2.0/loanapplication/546?view=status HTTP/1.1