在這個示例中，原始地址被分解為三個新資源：街道地址、城市和州。這樣一來，用戶可以選擇采用新資源，或者繼續使用舊的地址資源，確保現有集成的穩定性。

如何進行 API 版本控制？

實際上，API 需要時不時發布新版本，以解決重大錯誤、安全漏洞或進行性能改進。有時，API 的設計可能從一開始就存在缺陷，需要進行徹底的修正。為了確保這些更新不會中斷現有用戶的服務，API 版本控制變得至關重要。

在制定版本控制策略時，最重要的一點是確保向后兼容性。通過保持舊版本的 API 處于可用狀態并持續支持，使用戶可以繼續使用舊版本，直到他們準備好升級。這樣做實際上是通過分叉舊版本的 API 來創建新版本，同時保持舊版本的功能。

何時停用舊版本的 API 由具體情況決定。例如，分析使用數據可能會發現 v2 和 v3 的用戶數量遠遠高于 v1。如果繼續維護 v1 的成本高于潛在的用戶流失成本，那么可以考慮棄用 v1。

無論是小更新還是新版本發布，所有變更都應明確告知用戶。如果需要停用某個 API 功能或版本，必須提前通知用戶并給予他們充分的時間進行調整。需要預料到這種決定可能會導致一些用戶不滿，甚至流失——但希望不會太多。

關于棄用 API 組件的通知，可能如下所示：

## API 版本控制的類型有哪些？

在實際標記新版本時，有幾種方法可供選擇，其中一些方法可能比其他方法更適合用戶群體。以下是將客戶端 API 調用路由到不同 API 版本的幾種常用方法。

URI 路徑

對 API 進行版本控制的最常見方式是在 URI 路徑中進行版本標記。這種方法利用 URI 路由將請求定向到特定版本的 API。URI 不僅指定了目標資源，還指明了資源所在的版本。

https://www.example.com/api/v1/resource



or



https://apiv1.example.com/api/resource

版本標識符可以是數字、日期、名稱或其他唯一標識符，只要每個版本都是獨特的即可。

URI 路徑版本控制相對容易理解和實現。然而，如果舊版本的 API 未被保持在可用狀態，則用新版本號替換舊 URI 將導致使用舊版本的集成失效，客戶端將需要更新他們的軟件以繼續使用 API。

此外，這種方法不允許僅更新 API 的某一部分。每個端點都必須更新，這樣做不僅缺乏靈活性，還更耗費資源，需要為每個版本創建全新的 API。這也違反了 API 設計的一個關鍵原則：每個資源都應有其唯一的 URI。

Query 參數

在查詢參數版本控制方法中，版本號作為查詢參數包含在 URI 中，而不是在路徑中。

https://www.example.com/api/resource?version=1

這種方法相對容易實現，不需要在更新版本時修改所有 URI?？蛻舳丝梢酝ㄟ^在其請求中更改查詢參數來切換到新版本。如果客戶端未在其查詢中指定版本號，系統可以默認使用最新版本。

自定義請求標頭

您還可以使用請求和響應中的自定義標頭設置版本號。這不會改變資源的 URI。

Accept Header

使用 Accept 請求 HTTP 標頭進行 API 版本控制時，客戶端可以在請求頭中指定能夠處理的內容類型，從而確定所請求的 API 版本。例如：

Accept: application/vnd.example.v1+json

Accept: application/vnd.example+json;version=1.0

這種方法允許對單個資源進行版本控制，而不必一次性對整個 API 進行版本控制，從而為開發人員提供更細粒度的版本控制。這也意味著，開發人員可以在代碼庫中節省空間，因為不需要為每個新版本復制整個 API。

然而，這種方法的缺點是實現和測試起來更加復雜。開發人員需要跟蹤 API 的哪些部分屬于哪個版本，并且要確保每個客戶端都能獲取到正確的版本。這涉及更復雜的版本管理和交付邏輯，可能增加開發和維護的難度。

通過 API 版本控制保持您的集成完整

通過 API 版本控制保持集成的完整性至關重要。雖然更新 API 是必要的，但也伴隨著風險。如果沒有適當的版本控制，可能會出現問題，進而導致消費者失去信任，轉而尋找更穩定的替代方案。

每次進行更改時，都應盡量減少對客戶的影響，這也是正確實施 API 版本控制的核心目標。用戶可能不會直接表達感謝，但他們會繼續依賴并使用您的服務。