Mike Amundsen 有关 API 设计的研讨会（Workshop）

Mike Amundsen 是 Layer 7 公司的首席 API 架构师，也是“ Building Hypermedia APIs with HTML5 & Node ”一书的作者。他最近进行了一次全球巡讲，分别在芝加哥、悉尼、墨尔本和多伦多等地组织了一系列有关API 设计的研讨会。InfoQ 于7 月25 日参加了他在墨尔本举行的研讨会。

Amundsen 的设计技巧主要关注的是 USE 范型（ USE paradigm ），这是 Usable（易用）、Scalable（可伸缩）和 Evolvable（可演进）的缩写。Amundsen 描述了 3 种常用的 API 实现风格，并使用 USE 范型中的各种原则比较了其优缺点。

Amundsen 详细探讨了版本化（Versioning），建议“除非迫不得已，不要使用版本化”。应该首选演进式设计。

“易用性（Usability）是指人们设计的对象易于学习和使用”，Amundsen如是说。这提醒我们，API 从字面上看就是“接口”，应该以用户和任务为重点。他还说到，“请准备好实验测量，并在接口设计上进行迭代。”

“可伸缩性（ Scalability ）是系统处理不断增长的工作的能力。” Amundsen 提到，需要理解垂直伸缩（scale-up）和水平伸缩（scale-out）的区别。短期来看垂直伸缩比较容易，但不能持久。水平伸缩在短期内难于实现，但长期来看则更为可靠。Amundsen 建议使用 DevOps 实践来支持水平伸缩。

“可演进性（ Evolvability ）是系统适应演进的能力。”Amundsen 建议，只要可能就应该选择扩展 API，而不是版本化。“除非万不得已，不要进行版本化，而必须进行版本化的场合非常少。”版本化对内部代码管理是有意义的，但 Web API 用户关注的只是是否存在破坏。通过“绝不删除条目”的方式，我们可以在不破坏现有实现的情况下完成修改。扩展接口意味着绝不修改现有数据结构的意义，将所有新加入内容都设计为可选的（optional）。但有时我们不得不引入破坏性的变化，这时就要使用“版本化”了。在这种情况下，要使版本信息易于识别。“要使之易于构建，易于测试，而且不容易在多个流之间出现交叉”，Amundsen 提到。“要对客户端忽略这些信息有所准备，因为它们确实会这么做。”Amundsen 建议将版本标识符放在 URL 中，而不要放在首部或有效载荷中，以方便客户端忽略它们。

Amundsen 介绍了 3 种最常用的 API 实现风格：Tunnel 风格（SOAP）、URI 风格（CRUD）和超媒体风格（REST），并回顾了各种实现风格的历史及优缺点。他还强调，这些风格并不是标准的。

Tunnel 风格使用 SOAP 以独立于转移协议的方式转运消息。该风格主要关注函数和方法，有很好的易用性。对企业而言，该风格有很好的工具支持和较强的治理机制。然而，它也存在一些不足：栈依赖导致了一种“全有或者全无（all or nothing）”的限制，对 HTTP 支持较差，在程序员之间的受欢迎程度在不断下降等。在可演进性方面，SOAP 带来了很大的治理和版本化问题，因为即便模式（schema）上的微小变化，都有可能是破坏性的。Amundsen 指出，很多人都不再使用 SOAP 代理模型，而更多地将 SOAP 用作一种消息模型，这避免了很多缺点。

URI 风格使用 HTTP 动词和（通常是）JSON 数据结构来操控 Web 资源。Amundsen 提醒我们，该风格不是 REST 的，他引用了 Roy Fielding 在 2008 年的一篇博客中的论断：如果 API 不是超文本驱动的，那就不是 REST 的。URI 风格是一种面向对象或面向实体的风格，今天大量的公开 API 都使用了这种风格。HTTP 协议众所周知，对象池技术也不错，因此修改这样的 API 相对容易。然而该风格的易用性是有限制的，因为 HTTP 方法集较小，而且 URI 建模也不是标准的。用户必须把领域方法映射为资源和 HTTP 方法。Amundsen 指出，URI 风格“容易上手，但是难以伸缩和演进”。

Amundsen 最后描述了超媒体风格，或者说 REST 。相对于 URI 风格，超媒体风格引入了媒体类型和链接关系，Amundsen 认为这对消息各方达成共识至关重要，因此该风格的可用性有所增强。超媒体风格暴露出了任务和用例，而且在为文档化工作流程提供一种机器可读的方式这方面，它的做法与 SOAP 越来越接近。超媒体支持可演进性，这就使服务可以长期使用。但是人们认为这种风格深奥难懂，而且没有很好的工具支持。Amundsen 认为 Siren 这种超媒体框架非常有趣，值得一看。

Amundsen 经常向 InfoQ贡献内容。他与Leonard Richardson 和Sam Ruby 合著的新书“ RESTful Web APIs ”预计本月上市。

查看英文原文： Mike Amundsen Workshop on API Design