设计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设计成客户端使用的东西很重要。
比如说，在一个简单的待办事项列表应用中，你可能会找到下面这些语义描述符：
在一个功能完备的应用程序中，可能还会有很多语义描述符，涉及待办事项的分类（工作、家庭、园艺等），用户信息（用于多用户的实现）等等。不过为了突出过程本身，我们会保持它的简单性。
步骤2 : 绘制状态图
下一步是根据建议的API绘制出状态图。图中的每个框都表示一种可能的表示–一个包含在步骤1中确定的一或多个语义描述符的文档。你可以用箭头表示从一个框到下一个的转变–从一个状态到下一个状态。这些转变是由协议请求触发的。
在每次变化中还不用急着指明用哪个协议方法。只要标明变化是安全的（比如HTTP GET），还是不安全/非幂等的（比如HTTP POST），或者不安全/幂等的（PUT）。
说明：幂等动作是指重复执行时不会有无法预料的副作用。比如HTTP PUT，因为规范说服务器应该用客户端传来的状态值替换目标资源的已有值，所以说它是幂等的。而 HTTP POST是非幂等的，因为规范指出提交的值应该是追加到已有资源集合上的，而不是替换。
在这个案例中，我们这个简单的待办事项服务的客户端应用程序可能需要访问可用条目的清单，能过滤这个清单，能查看单个条目，并且能将条目标记为已完 成。这些动作中很多都用状态值在客户端和服务器之间传递数据。比如add-item 动作允许客户端传递状态值title和dueDate。下面是一个说明那些动作的状态图。
这个状态图中展示的这些动作（也在下面列出来了）也是语义描述符– 它们描述了这个服务的语义动作。
在你做这个状态图的过程中，你可能会发现自己漏掉了客户端真正想要或需要的动作或数据项。这是退回到步骤1的机会，添加一些新的描述符，并/或者在步骤2中改进状态图。
在你重新迭代过这两步之后，你应该对客户端跟服务交互所需的所有数据点和动作有了好的认识和想法。
步骤 3 : 调和魔法字符串
下一步是调和服务接口中的所有“魔法字符串”。“魔法字符串” 全是描述符的名称–它们没有内在的含义，只是表示客户端跟你的服务通讯时将要访问的动作或数据元素。调和这些描述符名称的意思是指采用源自下面这些地方的，知名度更高的公共名称：
这些全是明确定义的、共享的名称库。当你服务接口使用来自这些源头的名称时，开发人员很可能之前见过并知道它们是什么意思。这可以提高API的可用性。
说明：尽管在服务接口上使用共享名称是个好主意，但在内部实现里可以不用（比如数据库里的数据域名称）。服务自身可以毫不困难地将公共接口名称映射为内部存储名称。
以待办事项服务为例，除了一个语义描述符- create-item，我能找到所有可接受的已有名称。为此我根据Web Linking RFC5988中的规则创建了一个具有唯一性的URI。在给接口描述符选择知名的名称时需要折中。它们极少能跟你的内部数据存储元素完美匹配，不过那没关系。
这里是我的结果：
经过名称调和，我的状态图变成了下面这样：
步骤 4 : 选一个媒体类型当你感到悲哀痛苦时，最好是去学些什么东西。
