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

This entry was posted in Achitecture, Best Practices. Bookmark the permalink.

发表评论

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / 更改 )

Twitter picture

You are commenting using your Twitter account. Log Out / 更改 )

Facebook photo

You are commenting using your Facebook account. Log Out / 更改 )

Google+ photo

You are commenting using your Google+ account. Log Out / 更改 )

Connecting to %s