Web API设计方法论

Question

设计 Web API 不止是 URL、HTTP 状态码、头信息和有效负载。设计的过程--基本上是为了你的 API“观察和感受” -- 这非常重要，并且值得你付出努力。本文简要概括了一种同时发挥 HTTP 和 Web 两者优势的 API 设计方法论。并且它不仅对 HTTP 有效。如果有时你还需要 通过 WebSockets、XMPP、MQTT 等实现同样的服务，大部分 API 设计的结果同样可用。可以让未来支持多种协议更容易实现和维护。

优秀的设计超越了 URL、状态码、头信息和有效负载

一般来说， Web API 设计指南的重点是通用的功能特性，比如 URL 设计，正确使用状态码、方法、头信息之类的 HTTP 功能特性，以及持有序列化的对象或对象图的有效负载 设计。这些都是重要的实现细节，但不太算得上 API 设计。并且正是 API 的设计--服务的基本功能特性的表达和描述方式--为 Web API 的成功和可用性做出了重要贡献。

一个优秀的设计过程或方法论定义了一组一致的、可重复的步骤集，可以在将一个服务器端服务组件输出为一个可访问的、有用的 Web API 时使用。那就是说，一个清晰的方法论可以由开发人员、设计师和软件架构师共享，以便在整个实现周期内帮助大家协同活动。一个成熟的方法论还可以随着 时间的发展，随着每个团队不断发现改善和精简过程的方式而得到精炼，却不会对实现细节产生不利的影响。实际上，当实现细节和设计过程两者都有清晰的定义并相互分离时，实现细节的改变（比如采用哪个平台、OS、框架和 UI 样式）可以独立于设计过程。

API 设计七步法

接下来我们要对 Richardson 和 Amundsen 合著的《 REST 风格的 Web API 》一书中所介绍的设计方法论做简要地概述。因为篇幅所限，我们不能深入探讨这一过程中的每一步骤，但这篇文章可以让你有个大概的认识。另外，读者可以用这篇概述作为指南，根据自己组织的技能和目标开发一个独有的 Web API 设计过程。

说明：是的，7步看起来有点儿多。实际上清单中有5个步骤属于设计，额外还有两个条目是实现和发布。最后这两个设计过程之外的步骤是为了提供一个从头到尾的体验。

你应该计划好根据需要重新迭代这些步骤。通过步骤 2（绘制状态图）意识到在步骤 1（列出所有组成部分）有更多工作要做。当你接近于写代码（步骤 6） 时，可能会发现第 5 步（创建语义档案）中漏了一些东西。关键是用这个过程暴露尽可能多的细节，并愿意回退一步或者两步，把前面漏掉的补上。迭代是构建更加 完整的服务画面以及澄清如何将它暴露给客户端程序的关键。

步骤 1 : 列出所有组成部分

第一步是列出客户端程序可能要从我们的服务中获取的，或要放到我们的服务中的所有数据片段。我们将这些称为语义描述符。语义是指它们处理数据在应用 程序中的含义，描述符是指它们描述了在应用程序自身中发生了什么。注意，这里的视点是客户端，不是服务器端。将 API 设计成客户端使用的东西很重要。

比如说，在一个简单的待办事项列表应用中，你可能会找到下面这些语义描述符：

• id : 系统中每条记录的唯一标识符
• title : 每个待办事项的标题
• dateDue : 待办事项应该完成的日期
• complete : 一个是/否标记，表明待办事项是否已经完成了。

在一个功能完备的应用程序中，可能还会有很多语义描述符，涉及待办事项的分类（工作、家庭、园艺等），用户信息（用于多用户的实现）等等。不过为了突出过程本身，我们会保持它的简单性。

步骤 2 : 绘制状态图

下一步是根据建议的 API 绘制出状态图。图中的每个框都表示一种可能的表示--一个包含在步骤 1 中确定的一或多个语义描述符的文档。你可以用箭头表示从一个框到下一个的转变--从一个状态到下一个状态。这些转变是由协议请求触发的。

在每次变化中还不用急着指明用哪个协议方法。只要标明变化是安全的（比如 HTTP GET），还是不安全/非幂等的（比如 HTTP POST），或者不安全/幂等的（PUT）。

说明：幂等动作是指重复执行时不会有无法预料的副作用。比如HTTP PUT，因为规范说服务器应该用客户端传来的状态值替换目标资源的已有值，所以说它是幂等的。而 HTTP POST是非幂等的，因为规范指出提交的值应该是追加到已有资源集合上的，而不是替换。

在这个案例中，我们这个简单的待办事项服务的客户端应用程序可能需要访问可用条目的清单，能过滤这个清单，能查看单个条目，并且能将条目标记为已完 成。这些动作中很多都用状态值在客户端和服务器之间传递数据。比如 add-item 动作允许客户端传递状态值 title 和 dueDate。下面是一个说明那些动作的状态图。

这个状态图中展示的这些动作（也在下面列出来了）也是语义描述符-- 它们描述了这个服务的语义动作。

• read-list
• filter-list
• read-item
• create-item
• mark-complete

在你做这个状态图的过程中，你可能会发现自己漏掉了客户端真正想要或需要的动作或数据项。这是退回到步骤 1 的机会，添加一些新的描述符，并/或者在步骤 2 中改进状态图。

在你重新迭代过这两步之后，你应该对客户端跟服务交互所需的所有数据点和动作有了好的认识和想法。

步骤 3 : 调和魔法字符串

下一步是调和服务接口中的所有“魔法字符串”。“魔法字符串” 全是描述符的名称--它们没有内在的含义，只是表示客户端跟你的服务通讯时将要访问的动作或数据元素。调和这些描述符名称的意思是指采用源自下面这些地方的，知名度更高的公共名称：

• Schema.org
• microformats.org
• Dublin Core
• IANA Link Relation Values

这些全是明确定义的、共享的名称库。当你服务接口使用来自这些源头的名称时，开发人员很可能之前见过并知道它们是什么意思。这可以提高 API 的可用性。

说明：尽管在服务接口上使用共享名称是个好主意，但在内部实现里可以不用（比如数据库里的数据域名称）。服务自身可以毫不困难地将公共接口名称映射为内部存储名称。

以待办事项服务为例，除了一个语义描述符- create-item，我能找到所有可接受的已有名称。为此我根据 Web Linking RFC5988 中的规则创建了一个具有唯一性的 URI。在给接口描述符选择知名的名称时需要折中。它们极少能跟你的内部数据存储元素完美匹配，不过那没关系。

这里是我的结果：

• id -> 来自 Dublin Core 的 identifier
• title - 来自 Schema.org 的 name
• dueDate -> 来自 Schema.org 的 scheduledTime
• complete -> 来自 Schema.org 的 status
• read-list -> 来自 IANA Link Relation Values 的 collection
• filter-list -> 来自 IANA Link Relation Values 的 search
• read-item -> 来自 IANA Link Relation Values 的 item
• create-item ->用 RFC5988 的 http://mamund.com/rels/create-item
• mark-complete - 来自 IANA Link Relation Values 的 edit

经过名称调和，我的状态图变成了下面这样：

步骤 4 : 选一个媒体类型

API 设计过程的下一步是选一个媒体类型，用来在客户端和服务器端之间传递消息。Web 的特点之一是数据是通过统一的接口作为标准化文档传输的。选 择同时支持数据描述符（比如"identifier"、"status"等）和动作描述符（比如"search"、"edit"等）的媒体类型很重要。有相当多可用的格式。

在我写这篇文章时，一些顶尖的超媒体格式是 (排名不分先后)：

• 超文本标记语言 ( HTML )
• 超文本应用程序语言( HAL )
• Collection+JSON ( Cj )
• Siren
• JSON-API
• 交换表达式的统一基础 ( UBER )

让所选择的媒体类型适用于你的目标协议也很重要。大多数开发人员喜欢用 HTTP 协议做服务接口。然而 WebSockets 、 XMPP 、 MQTT 和 CoAP 也会用--特别是对于高速、短消息、端到端的实现。

在这个例子中，我会以 HTML 为消息格式，并采用 HTTP 协议。HTML 有所有数据描述符所需的支持(<UL>用于列表， <LI>用于条目， <SPAN>用于数据元素)。它也有足够的动作描述符支持 (<A>用于安全链接， <FORM method="get">用于安全转变， <FORM method="post">用于非安全转变）。

注意：在这个状态图中， “编辑”动作是幂等的（比如HTTP PUT），并且HTML仍然没有对PUT的原生支持。在这个例子中，我会添加一个域来将HTML的POST做成幂等的。

好了，现在我可以基于那个状态图创建一些样例表示来“试试”这个接口了。对我们的例子而言，只有两个表示要渲染：“待办事项列表”和“待办事项条目”表示：

图1 ：用HTML表示待办事项列表集合

图 2：用HTML表示待办事项条目

记住，在你做状态图的表示样例时，可能会发现之前的步骤中有所遗漏（比如漏掉描述符，动作描述符中有幂等之类的变化等）。那也没关系。现在就是解决所有这些问题的时机-- 在你把这个设计变成代码之前。

等你对表示完全满意之后，在开始写代码之前还有一个步骤--创建语义档案。

步骤 5 : 创建语义档案

语义档案是一个文档，其中列出了设计中的所有描述符，包括对开发人员构建客户端和服务器端实现有帮助的所有细节。这个档案是一个实现指南，不是实现描述。这个差别很重要。

服务描述符的格式

服务描述文档格式已经出现了相当长一段时间了，并且当你想给已有的服务实现生产代码或文档时很方便。确实有很多种格式。

在我写这篇文章时，顶级竞争者有：

• Web 服务定义语言( WSDL )
• 原子服务描述( AtomSvc )
• Web 应用程序描述语言( WADL )
• Blueprint
• Swagger
• REST 风格的应用程序建模语言( RAML )

档案的格式

现在只有几种档案格式。我们推荐下面两种：

• 应用级语义档案 ( ALPS )
• JSON-LD + Hydra

这两个都比较新。JSON-LD 规范在 2014 年早期达成了 W3C 推荐状态。Hydra 仍是一个非官方草案（本文写成时还是），有一个活跃的开发者社区。ALPS 仍处于 IETF 的早期草案阶段。

因为档案文档的理念是要描述一个问题空间的现实生活方面（不只是那一空间中的单一实现），所以其格式跟典型的描述格式十分不同：

图3 : ALPS格式的待办事项列表语义档案

你会注意到，这个文档就像一个基本的词汇表，包含了待办事项服务接口中所有可能的数据值和动作--就是这个理念。同意遵循这个档案的服务可以自行决定它们的协议、消息格式甚至 URL。同意接受这个档案的客户端将会构建为可以识别，如果合适的话，启用这个文档中的描述符。

这种格式也很适合生成人类可读的文档，分析相似的档案，追踪哪个档案用得最广泛，甚至生成状态图。但那是另外一篇文章的课题了。

现在你有完整的已调和名称的描述符清单，已标记的状态图，以及一个语义档案文档，可以开始准备编码实现样例服务器和客户端了。

步骤 6 : 写代码

到了这一步，你应该可以将设计文档（状态图和语义档案）交给服务器和客户端程序的开发人员了，让他们开始做具体的实现。

HTTP 服务器应该实现在第 2 步中创建的状态图，并且来自客户端的请求应该触发正确的状态转变。服务发送的每个表示都应该用第 3 步中选好的格式，并 且应该包含一个第 4 步中创建的指向一个档案的链接。响应中应该包含相应的超媒体控件，实现了在状态图中显示、并在档案文档中描述的动作。客户端和服务器端 开发人员在这时可以创建相对独立的实现，并用测试验证其是否遵守了状态图和档案。

有了稳定的可运行代码，还有一步要做：发布。

步骤 7 : 发布你的 API

Web API 应该至少发布一个总能给客户端响应的 URL -- 即便是在遥远的将来。我将其称为“看板 URL” --每个人都知道的。发布档案文档也是个好主意，服务的新实现可以在响应中链接它。你还可以发布人类可读的文档、教程等，以帮助开发人员理解和使用你的服 务。

做好这个之后，你应该有了一个设计良好的、稳定的、可访问的服务运行起来了，随时可以用。

总结

本文讨论了为 Web 设计 API 的一组步骤。重点是让数据和动作描述正确，并以机器可读的方式记录它们，以便让人类开发人员即便不直接接触也能轻松为这个设计实现客户端和服务器端。

这些步骤是：

1. 列出所有组成部分
   收集客户端跟服务交互所需的所有数据元素。
2. 绘制状态图
   记录服务提供的所有动作（状态变化）
3. 调和魔法字符串
   整理你的公开接口以符合（尽可能）知名的名称
4. 选择媒体类型
   评审消息格式，找到跟目标协议的服务转变最贴近的那个。
5. 创建语义档案
   编写一个档案文档，定义服务中用的所有描述符。
6. 写代码
   跟客户端和服务器端开发人员分享档案文档，并开始写代码测试跟档案/状态图的一致性，并在有必要时进行调整。
7. 发布你的 API
   发布你的 看板 URL 和档案文档，以便其他人可以用他们创建新的服务以及/或者客户端程序。

在你的设计过程中，你可能会发现有遗漏的元素，需要重做某些步骤，以及要做一些折中的决定。这在设计过程中出现得越早越好。将来开发人员要求用新的格式和协议实现时，你还有可能用这个 API 设计。

最后，这个方法论只是为 Web API 设计过程创建一种可靠、可重复、一致的设计过程的一种可能方式。在你做这个例子时，可能会发现插入一些额外的步骤，或者缩减一些会更好用，并且-- 当然 -- 消息格式和协议决策在不同案例中可能也会发生变化。

希望这篇文章能给你一些启发，让你知道如何给自己的组织以及/或者团队创建一个最佳的 API 设计方法论。