API 版本策略

改變是不可避免的。但破壞使用者的程式碼卻不是。API 版本控制允許您在演進 API 的同時，讓現有的整合保持運作。

何時進行版本控制？

非破壞性變更：新增一個可選欄位。 -> 不需要更改版本（或次要修補程式）。

破壞性變更：重新命名欄位、移除參數、更改資料類型。 -> 需要新版本。

在 REST 中處理版本控制主要有三種方式：

將版本包含在 URL 路徑中。

GET /v1/users

GET /v2/users

優點：明確、易於快取、易於在瀏覽器中探索。

缺點：「汙染」了 URI 資源空間。

將版本包含在自訂 Header 中。

Accept-Version: v1

優點：URI 保持乾淨（GET /users 永遠是路徑）。

缺點：較難在瀏覽器中測試（需要擴充功能），快取較棘手。

GET /users?version=1

優點：易於實作。

缺點：可能會與其他查詢參數混淆。

您無法永遠支援所有版本。

Sunset Header：使用 Sunset HTTP Header 來宣佈端點何時停止運作。

Sunset: Sat, 31 Dec 2025 23:59:59 GMT

溝通：提前透過電子郵件通知您的開發者（對於主要 API，需提前 6 到 12 個月）。

Brownouts（部分停機）：短暫、有計畫地停止舊 API 的運作，以引起忽略電子郵件的開發者的注意。

避免破壞：盡可能進行疊加式變更（非破壞性），以避免版本控制的成本。

明確：URI 版本控制 (/v1) 由於其清晰性，是公共 API 的產業標準。

為死亡做計畫：您誕生的每個版本都需要一個最終如何退役的計畫。

繼續閱讀 → API 的未來