如何版本化你的API？

**：infoq，

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

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

uri中設定版本

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

curl

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

http頭中設定版本

這種方式的版本資訊會放在http的請求頭中，通常會利用accept字段，或者自定義乙個字段。例如：

curl  \

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

沒有版本

版本化的目的是為了標識api的變化，如果api不會變化，或者每次都會重新擴充套件新的api，這種情況下，就可以標識版本資訊。例如：

curl

一種折中方案

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

大版本更新，例如字段型別變更、資料物件變更等。這種情況下無法滿足對客戶端的向下相容，因此需要修改版本號。

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

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

使用者管理平台

乙個常用的使用者管理平台，提供以下api，通過使用者id獲取使用者資訊：

curl

...

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

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

curl

...

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

curl

...

這種情況下，基本可以做到向下相容，因此可以算是「小版本公升級」。針對小版本公升級，可以將小版本號放到http頭中。例如：

curl \

-h 'api-version: 20170801'

...

後端路由

由於混合版本化的方式同時涉及到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的保留時間。

如何版本化你的API？

如何保護你的API

如何優雅的管理不同版本的API介面

Apple如何知道你用私有API？

如何版本化你的API？

如何保護你的API

如何優雅的管理不同版本的API介面

Apple如何知道你用私有API？

相關推薦