HTTP API 可演进性最佳实践

正如标题所示，Benjamin Carlyle 试图在《Best Practices For HTTP API Evolvability》一文中为围绕 HTTP API 构建的系统的设计定义原则和实践，这些系统是可扩展的，并且能一直进化下去。他先指出了 REST（一种架构风格）和 HTTP API（通过 HTTP 暴露的编程接口）之间的区别。

HTTP API 是针对一个特定服务的面向开发者的接口，也被称为 RESTful 服务契约、面向资源架构或 URI Space 。

我说 REST 和 HTTP API 紧密相关是因为大多数 HTTP API 并不严格遵守统一接口约束，严格说来统一接口约束要求接口是“标准的”[…]

文章开头他标识出了 API 设计中的不同元素，这些元素决定了 API 后续的进化。通常来说，API 进化涉及到了设计客户端与服务器的兼容性；特别是 API 的向后和向前兼容变更。 变更频率按增序排列依次是：

1. API 中用到的方法的通用语义，包含异常条件和其他元数据
2. API 中用到的媒体类型的通用语义，包含全部 Schema 信息
3. 构成 API 的 URI 集合，包含 API 中用到的每个通用方法和媒体类型的特定语义

API 进化中改变最少的就是方法的语义。文中描述的最佳实践是识别出向前和向后兼容的变化，运用 Postel 法则让服务与客户端以一种更能容忍的方式进行进化。他建议尽可能地使用 HTTP 错误码来传达兼容性问题。

最佳实践 3：新方法名应该选择那些不会和任何已有方法发生向前兼容的名字。例如，如果要处理的方法必须正确理解（必须理解语义）方法的新特性，那么应该选择一个新的方法名。

最佳实践 4：服务应该忽略它们不理解的标头或组件。代理应该不加修改地传递这些标头，或者是无法理解的组件。

[…]

最佳实践 7：在某个数字范围内为新状态分配一个状态码，这个范围可以粗粒度地标识已存在的条件。

[…]

最佳实践 9：如果新状态是一个已知状态（除了 400 Bad Request 或 500 Internal Server Error）的子集，可以向响应头添加信息来细化已知状态的含义，而不是分配一个新的状态码。

他指出了一个重要的区别，即客户端与服务器交互中媒体类型的对称本质。

[…] 与客户端和服务器之间非对称的方法和状态不同，媒体类型通常能用作请求或响应的负载，即适用于两个方向。为此本节中我们不讨论客户端与服务器，而是讲发送端与接收端。

…这构成了与媒体类型相关的最佳实践的基础

[…]

最佳实践 11：只有当验证逻辑是为与文档发送方相同版本或后续版本的 API 编写的情况下，才可能出现不符合最佳实践 10 的文档验证。

最佳实践 12：在不违反媒体类型设计目标的前提下，如果能向现有媒体类型的 Schema 中添加新信息，那么就添加吧。

他提倡使用 Content-Types 和 Accept 标头来管理发送端与接收端之间的兼容性。

HTTP API 习惯于做出向后不兼容的媒体类型 Schema 变更。新客户端请求或者提供了 Schema 中带有向后不兼容变更的新媒体类型。老的客户端继续请求或提供旧的媒体类型。直到所有重要的相关实现都升级到最新的媒体类型集之前，客户端与服务器端都应该要支持旧的媒体类型。

他认为对资源的修改，尤其是 URI 的修改都是服务器应该关心的事；如果客户端是设计成由超媒体约束驱动的话，一般这些修改都不应该引入兼容性问题。他提倡使用 Cookies 将客户端请求路由到合适的服务实例 / 服务器。

在使用多种通用方法时，我们不再处理通用的方法或媒体类型，而是和带有特定语义的特定 URL 打交道。[…] 在考虑如下服务契约时，我倾向于采用以服务器为中心的视角：

• GET /invoice/{invoice-id}，返回媒体类型 application/invoice+xml，内容是 invoice-id 指定的发货单
• GET /invoice/{invoice-id}/paid，返回媒体类型 text/plain（ xsd:bool 语法），内容是 invoice-id 指定的发货单的支付状态
• PUT /invoice/{invoice-id}/paid，接受媒体类型 text/plain（ xsd:bool 语法），设置 invoice-id 指定的发货单的支付状态

此外，他还提出了一些客户端的最佳实践，以便客户端能应对服务器 URI 的转变（transition）和进化。

最佳实践 19：在升级时，服务应该通过 Cookies 追踪哪些客户端应该连接到旧的服务器，哪些应该连接到新的服务器，或者也可以使用类似的机制。

最佳实践 20：即使不是在响应 HEAD 或 GET 请求，客户端也应该遵从服务器发回的重定向状态响应 [说明： RFC2616 ]。

最佳实践 21：重新设计 URL 时，确保新的 URL 拥有和旧 URL 一样的语义，并将旧 URL 重定向到新的 URL 上。

本文中提供了一些基本原理，让 HTTP API 系统能随着时间不断进化。请务必阅读 Benjamin Carlyle 的完整原文以便对这一主题能有更深入的理解。

查看英文原文： Best Practices For HTTP API Evolvability