Mike Amundsen 有关 API 设计的研讨会(Workshop)

  • Saul Caganoff
  • 臧秀涛

2013 年 9 月 11 日

话题:REST架构

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

REST架构