一步一步演進RESTful API版本 - frankel

> curl http://org.apisix/hello
Hello world

> curl http://org.apisix/hello/Joe
Hello Joe

使用 API 閘道器
第一步也是最關鍵的一步是停止將應用程式直接暴露在網際網路上，並在它們之間建立一個 API 閘道器。
 

版本化 API
演進 API 意味著 API 的多個版本需要在某個時候共存。
三種方法：

curl http://org.apisix/hello?version=1
curl http://org.apisix/hello?version=2
 
curl -H 'Version: 1' http://org.apisix/hello
curl -H 'Version: 2' http://org.apisix/hello
 
curl http://org.apisix/v1/hello
curl http://org.apisix/v2/hello

> curl http://org.apisix/hello 
Hello world 

> curl http://org.apisix/v1/hello 
Hello world

將使用者從非版本化路徑遷移到版本化路徑
我們已經對 API 進行了版本控制，但我們的使用者可能仍在使用舊的非版本控制 API。我們希望他們遷移，但我們不能只刪除舊路由，因為我們的使用者不知道它。幸運的是，301 HTTP 狀態碼是我們的朋友：我們可以讓使用者知道資源已經從 http://org.apisix/hello 移動到了 http://org.apisix/v1/hello。它需要在初始路由上配置重定向外掛：

curl http://apisix:9080/apisix/admin/routes/1 -H 'X-API-KEY: xyz' -X PATCH -d '
{
  "plugins": {
    "redirect": {
      "uri": "/v1$uri",
      "ret_code": 301
    }
  }
}'

瞭解你的使用者
您可能已經注意到，到目前為止，我們不知道誰在使用我們的 API。當我們不得不引入改變時，我們必須要有創意，不要破壞使用者的使用。其他變化可能並不那麼容易應對。因此，我們應該努力瞭解我們的使用者，以便在必要時與他們聯絡。
 

建立使用者
您可能應該開始看到您的使用者訪問註冊頁面，具體取決於您限制未經身份驗證的使用量。註冊有很多方面；有可能：

• 自動化或需要儘可能多的手動驗證步驟
• 免費或付費
• 就像在沒有進一步驗證的情況下詢問電子郵件一樣簡單，或者像需要更多資料一樣複雜
• 等等。

生產測試
在這個階段，我們現在準備讓使用者瞭解我們的 Hello world API 的改進版本。我假設我們的團隊對其進行了徹底的測試，但新程式碼總是有風險的。部署現有應用程式的漏洞百出的新版本可能會對 API 提供商的形象（以及收入！）產生負面影響。
 

棄用舊版本
大多數使用者可能會遷移到新版本以從中受益，但其中一小部分會留在 v1.1 上。這可能有多種原因：沒有合適的時間（提示：它永遠不會）、太貴、沒有足夠的遷移動力，等等。但作為 API 提供者，每個部署的版本都有一定的成本。您可能需要在某個時候停用 v1。
 

結論
在這篇文章中，我們描述了一個簡單的分步流程來管理 API 的生命週期：

1. 不要直接暴露你的 API；前面設定一個API閘道器
2. 使用路徑、查詢引數或請求標頭對現有 API 進行版本控制
3. 將使用者從未版本化端點遷移到具有 301 狀態程式碼的版本化端點
4. 輕輕推動您的使用者註冊
5. 在生產中進行測試，首先複製流量，然後將一小部分使用者轉移到新版本
6. 正式釋出新版本
7. 透過標準響應標頭傳達舊版本的棄用

• https://stripe.com/blog/api-versioning
• https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis
• https://apigility.org/documentation/api-primer/versioning