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

Advertisements
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