原文地址：http://www.infoq.com/cn/news/2017/09/How-versioning-API

如何版本化API需要考慮各種實際業務場景，但是一個完備的API應該是：

• 和客戶端交互的約定。API需要確保穩定性，預先定義各種可能返回狀態，包括各種異常。客戶端無需考慮約定之外的情況。
• 向下兼容。在API沒有變化的時候，API實現的更新和升級，都應該確保原有客戶端請求不出現問題。
• RESTful。API設計應該能夠遵照RESTful風格，通過URI來表示資源，通過HTTP GET、POST、PUT、DELETE等方法表示操作行為。

為了滿足上述約定，版本化API不失為一種保持兼容性的好方法。版本化API的通常方式有：

URI中設置版本

這種方式通常在URI中增加一段用于標識版本，例如/v1、/v2等。例如：

curl https://example.com/api/v2/lists/3

這種方式的優勢在于版本信息很容易明顯的看出來，可以通過瀏覽器直接訪問。

HTTP頭中設置版本

這種方式的版本信息會放在HTTP的請求頭中，通常會利用Accept字段，或者自定義一個字段。例如：

curl https://example.com/api/lists/3 \ -H 'Accept: application/vnd.example.v2+json'

這種方式的好處是當版本升級時，URI保持不變，并且僅用于表示資源定位。

沒有版本

版本化的目的是為了標識API的變化，如果API不會變化，或者每次都會重新擴展新的API，這種情況下，就可以標識版本信息。例如：

curl https://example.com/api/lists/3

一種折中方案

前面提到了三種版本化API的方式，通常情況下需要針對自己業務的特殊性來挑選其中的一種方式。但是，在實際應用場景中，情況會更加復雜，API的升級通常有兩種情況：

大版本更新，例如字段類型變更、數據對象變更等。這種情況下無法滿足對客戶端的向下兼容，因此需要修改版本號。

小版本更新，例如增加可選參數、增加返回字段等。這種情況對于新客戶端可以增加功能，對于老客戶端仍然可以保持原有功能，可以不修改版本號。

因此，本文提出的折中方案是基于URI中的大版本號和HTTP頭中的小版本號整合的方式。下面通過一個簡單的示例來解釋。

用戶管理平臺

一個常用的用戶管理平臺，提供以下API，通過用戶ID獲取用戶信息：

curl https://example.com/api/v1/user/1 ... {"id": 1,"name": "test","email": "test@example.com" }

考慮以下兩種變動情況：一種是用戶id從數字變成了字符串，另一種是新增一個用戶頭像的值。

前者修改因為數據類型的變化，會導致客戶端解析出現問題。因此這樣的修改已經破壞了向下兼容性，此時就需要修改API的版本號。例如：

curl https://example.com/api/v2/user/1 ... {"id": "1","name": "test","email": "test@example.com" }

第二種情況，對于舊客戶端來說，只是增加了不使用的字段，通常的JSON格式解析庫都可以忽略這些不使用的字段。對于新客戶端則可以讀取新的字段。例如：

curl https://example.com/api/v2/user/1 ... {"id": "1","name": "test","email": "test@example.com","avatar": "http://example.com/1.jpg" }

這種情況下，基本可以做到向下兼容，因此可以算是“小版本升級”。針對小版本升級，可以將小版本號放到HTTP頭中。例如：

curl https://example.com/api/v2/user/1 \-H 'API-VERSION: 20170801' ... {"id": "1","name": "test","email": "test@example.com","avatar": "http://example.com/1.jpg" }

后端路由

由于混合版本化的方式同時涉及到URI和HTTP頭字段，前端代理（例如HAProxy、nginx）可以通過這些特定版本號字段將請求代理到對應的后端應用。

例如，前端使用HAProxy進行多版本分發，可以針對URI和HTTP頭定制acl，然后再對這些acl進行組合，設置不同的backend。

acl is_v1 path_beg /api/v1 acl is_v2 path_beg /api/v2 acl is_version_1 hdr(API-VERSION) 20170801 acl is_version_2 hdr(API-VERSION) 20170701 use_backend old_server if is_v1 is_version_1 use_backend new_server if is_v2 is_version_2 backend old_server ... backend new_server ...

這樣可以將API版本化規則應用到不同的后端，以保證向下兼容性。

總結

基于本文版本化API規則，將“大版本”應用在URI上，將“小版本”應用在HTTP頭字段上。通常來說，如果API升級之后破壞了向下兼容性，就應該升級“大版本”號；如果API升級可以向下兼容，可以升級“小版本”號。

版本化API有很多不同的設計方式，本文僅是其中一種。實際應用時，還是要根據業務場景進行選擇，包括API版本升級頻率，API穩定性等。通過HAProxy、nginx等代理服務，可以在確保向下兼容的情況下，由業務方決定老版本API的保留時間。

轉載于:https://www.cnblogs.com/davidwang456/p/7521792.html

總結

以上是生活随笔為你收集整理的如何版本化你的API？--转的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。