RESTful API版本控制策略

作RESTful开放平台，一方面其API变更越少，对API调用者越有利；另外一方面，没有人能够预测将来，系统在发展的过程当中，不可避免的须要添加新的资源，或者修改现有资源。

所以，改动升级必不可少，可是，做为平台开发者，你必须有觉悟：一旦你的API开放出去，有人开始用了，你就不能只管本身Happy了，你对平台的任何改动都须要考虑对当前用户的影响。

所以，作开放平台，你从第一个API的设计就须要开始API的版本控制策略问题，API的版本控制策略就像是开放平台和平台用户之间的长期协议，其设计的好坏将直接决定用户是否使用该平台，或者说用户在使用以后是否会由于某次版本升级直接弃用该平台。

API的版本控制策略一般有3种模式：

第一种：The Knot：无版本，即平台的API永远只有一个版本，全部的用户都必须使用最新的API，任何API的修改都会影响到平台全部的用户。甚至平台的整个生态系统。

第二种：Point-to-Point：点对点，即平台的API版本自带版本号，用户根据本身的需求选择使用对应的API，须要使用新的API特性，用户必须本身升级。

第三种：Compatible Versioning：兼容性版本控制，和The Knot同样，平台只有一个版本，可是最新版本须要兼容之前版本的API行为。

三种策略对整个平台在升级API的开销对好比下：

以上信息来源于这篇文章： http://www.ebpml.org/blog2/in... 做者以数学的方式详细的论述了这三种模式下，整个平台在升级API上的开销对比。

针对上面的论述，首先，API必定得有版本，不然升级对于用户来讲将是噩梦。其次，要作到Compatible Versioning有现实的限制，毕竟API升级时，不可避免的会出现没法兼容老版本的情况，所以，版本控制须要结合第二种和第三种模式，即提供一个统一的兼容版本入口，同时对于不能兼容历史版本的API保留历史版本，支持用户可以调用到历史版本的API。另外，对历史版本的API支持必定要有时间和用户限制，即老版API支持到必定时间就删除，新用户必须使用新版API，不然一个API有10个版本会让平台的维护很是痛苦。

URI vs Request Parameter vs Media Type
在RESTful API领域，关于如何作版本控制，目前业界比较主流的有3种作法：

第一种：URI， 即在URI中直接标记使用的是哪一个版本，无版本号URI默认使用最新版本。以下：

http://xianlinbox/api/customers/1234 
http://xianlinbox/api/v3.0/customers/1234

好处：
直接能够在URI中直观的看到API版本，能够直接在浏览器的查看各个版本API的结果.

坏处：
版本号在URI中破坏了REST的HATEOAS（hypermedia as the engine of application state）规则。版本号和资源之间并没有直接关系。

第二种：Request Parameter， 即在每一个请求后添加一个version参数，表示请求的是哪一个版本。以下：

http://server:port/api/customer/123?version=2

这种作法其实就是URI方式的变种，好坏处也都同样。

第三种： Mdedia Type， 即在HTTP请求的header中使用Media Type标记该请求想获取的资源， 一样的能够不设置或设置通用的Media Type表示最新版本的API。

===>
GET /customer/123 HTTP/1.1
Accept: application/vnd.xianlinbox.customer-v3+json

<===
HTTP/1.1 200 OK
Content-Type: application/vnd.xianlinbox.customer-v3+json

{"customer":
  {"name":"Xianlinbox"}
}

好处：
遵循了REST的设计风格.

坏处：
版本不直观，须要能设置header的client才能调用查看该API的效果。

原文：http://itindex.net/detail/470...版本控制