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...版本控制