Web API 的设计方法

为Web设计、实现和维护API不仅仅是一项挑战；对很多公司来说，这是一项势在必行的任务。本系列 将带领读者走过一段旅程，从为API确定业务用例到设计方法论，解决实现难题，并从长远的角度看待在Web上维护公共API。沿途将会有对有影响力的人物的访谈，甚至还有API及相关主题的推荐阅读清单。

这篇 InfoQ文章是 Web API从开始到结束系列文章中的一篇。你可以在这里进行订阅，以便能在有新文章发布时收到通知。

设计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 : 一个是/否标记，表明待办事项是否已经完成了。

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