Web API 的版本控制方案分析

源于对 OpenStack Api 版本控制约束问题的探讨，Mark Nottingham 在其博客中分析了云中 Web API 各种版本控制机制。他说，如果将 Web 上的版本 控制与软件版本控制做比较的话，软件版本控制成熟得多，而且一般来说更易于理解。

开发者们习惯了软件版本控制。譬如，在每次发版时都会推出一个版本号。版本号通常包含主版本号和小版本号，有时也会有诸如包版本号之类的称呼。 这种细粒度的版本标识对开发者和用户都非常有益；这些标识的简洁语义有助于判断兼容性和开发过程中的调试。

他接着说，但是，这样的版本思路不能很好地转化成 Web API 的版本控制。

使用了前一 API 版本的用户必须要判断如何用新版 API 进行工作。虽然他们猜测两个版本间应该是兼容的，但是他们却无法肯定。所以，他们仍然需要重写一堆 API。

[……] 简单地将软件版本控制的方法用于 Web API 也抵消了人们使用 HTTP 时得到的许多价值。如果你非要这么做，还不如使用“愚钝”的 RPC 协议。

Mark 认为，Web API 版本控制的主旨是保留与现有用户的兼容性。

一个基本原则是，不能破坏现有用户。他们实现了什么，你无从得知，也无法控制。

他还指出：

[……]Web API 的版本控制本质上是非线性的。换言之，当你产生一个新标识符时，你就产生了一个全新的东西，不论它是一个 HTTP 头、媒体类型标识还是一个 URI。你甚至可以用“foo”和“bar”来代替“V1”和“V2”。

他还就如何使用 HTTP 头的扩展机制实现多种版本控制给出了样例。他倡导通过产品令牌（product tokens）标识并解决实现问题。

他将 Web 上的版本控制分为两类：表现格式变更和资源变更。

很多人（如 Dave ）已经充分讨论过表现格式变更的问题了。它们既简单又复杂得让人恼火。总而言之，不要做向后不兼容的更改，如果非要做，就得改变媒体类型。

Mark 认为对资源的变更是一个更为有趣的问题。URI 是经历过尝试和测试的大众较接受的版本控制方法。接受度差一点的方法是超媒体（hypermedia ）。

REST 迷们研究在 Web API 中使用 HATEOS 标识已经有很长时间了，而且 Roy 也对许多人不知道这一方法表示惋惜。

Mark 的文章中也就使用超媒体公布资源元数据的方法给出了示例。客户端可以通过这些元数据以及服务端提供的各自资源模板来生成 URI。

这样，你就不再需要为接口生成不同的 URI，因为由代理驱动的内容商定能够有效地使用这一入口。

他承认有些人赞同使用 HATEOAS，也有些人反对，但是该解决方案带来的扩展性优势能够作为支持它的强有力的论据。

我认为，[译注：HATEOAS] 的核心观点是，URI 已经用于表示太多东西了——持久标识符、缓存键值、相关性解析、书签等——若再加上版本控制和扩展信息，超负荷使用 URI 的结果只能使其使用效果更差。通过把这些关注点转移到 HATEOAS 的链接关系和媒体类型中，你得到的是一个灵活的、拥抱未来的系统，它能够以可控的方式演进，而无需放弃享受 HTTP（不考虑 REST 了）的益处。

这里有作者原始的分析。

查看英文原文： Analysis Of Web API Versioning Options