對API進行版本控制的重要性和實現方式

我在API設計中收到的最多見問題之一就是如何對API進行版本控制。雖然並不是全部API都徹底相同，但我發如今API版本控制方面，某些模式和實踐適用於大多數團隊。我已經將這些內容收集起來，下面將提供一些關於版本控制策略的建議，該策略將幫助大多數API提供商，不管他們是向內部署API，仍是對外的API。

API版本真的那麼重要嗎？

API是你與API使用者之間創建的紐帶。正常狀況下，大家之間的紐帶不會輕易的斷開。紐帶包括URI模式，有效負載結構，字段和參數名稱，預期行爲以及其餘內容。這種方法的最大好處是顯而易見的：API使用者的理解不會變動，應用程序能夠保證持續有效。

可是，永久不變是不現實的。有時由於業務變化，你可能須要對API進行重大改變。發生這種狀況時，最好的方式是，你確保不會作任何會致使API使用者修復代碼的事情。

打破與不間斷的變化

非破壞性變動每每就像是「添加劑」，通常是添加新字段或嵌套資源到資源陳述，又或是增長新的端點，如PUT或PATCH。API使用者從一開始應該構建可以適應這些非破壞性更改的客戶端代碼。

突破性變化包括：

1.名字段或資源路徑，一般在API發佈後爲了統一命名規範。

2.更改有效負載結構，通常是適應如下內容：

• a.重命名或刪除字段
• b.將字段從單個值更改成一對多關係（好比從一個賬戶的一個電子郵件地址移動到這個賬戶的電子郵件地址列表）。
• c.修改了API的URL，致使返回結果不一致的狀況。

簡而言之，一旦你將API對外公開發布，你就必須保持它是可用的而且不會影響到使用者的。若是您遇到多個項目，則須要對API進行版本控制，以防止破壞現有的API使用者。

定義API版本策略

任何不斷髮展變化的API都須要API版本控制策略。你的API版本能夠適應根據API使用者的指望而切換不一樣版本變得有所不一樣。我一般建議將如下API版本控制策略做爲總體API管理系統的一部分。

1.若是你的API處於早期測試版本中，爲了得到消費者的反饋，請創建您的API可能會發生變化的正確指望。在此階段內，你會保留這個版本一段時間，由於你的API設計可能還會更改。做爲消費者，API是不穩定的，所以他們應該預期到可能會發生的變化。

2.一旦發佈，你的API應被視爲契約，若是沒有新版本，則不能被替換。

3.不間斷的更改會致使次要版本出現問題，客戶端會自動遷移到最新版本，不會出現任何負面反作用。

4.突破性的變化意味着客戶必須遷移到此新版本，由於它包含一個或多個重大更改。你必須與API使用者創建適當的時間表並按期溝通，以確保他們能方便地遷移到新版本。但在某些狀況下，這可能沒法立刻實現，因此你的團隊將會被要求暫時性支持之前的API版本。

什麼時候必須實現API版本控制

一旦肯定須要新版本的API，就須要知道如何處理它。實現API版本控制有三種經常使用方法。

1.資源版本控制

該版本是HTTP請求中Accept標頭的一部分，例如，Accept:application/vnd.github.v3+json 發送到GET /customers。這考慮了許多版本控制的首選形式，由於資源在版本化的同時須要保持URI相同。若是未在Accept標頭中提供，某些API會選擇提供最新版本做爲默認版本。

2.URI版本控制

該版本是URI的一部分，做爲前綴或後綴，例如，/v1/customers 或/customers/v1。雖然URI版本控制不如基於內容的版本控制那麼精確，但它每每是最多見的，由於它適用於不支持自定義標頭的各類工具。缺點是資源URI隨每一個新版本而變化，有些人認爲這與擁有永不改變的URI的意圖背道而馳。

3.主機名版本控制

該版本是主機名的一部分而不是URI，例如，https://v2.api.myapp.com/customers。當技術限制阻止基於URI或Accept標頭到API的正確後端版本時，將使用此方法。

備註：不管您選擇哪一個選項，API版本都只應包含主要編號。不須要小數字（即  /v1/customers，不是/v1.1/customers）。

實現版本控制的工具

使用工具和技術能夠從根本上實現API版本控制過程。用市場上優秀的API編輯器將使技術開發團隊可以在更短的時間內生成並切換更多的API版本，從而不斷改進設計決策。

結合工具進行版本控制是大多數開發過程的重要組成部分。API設計領域中也有這種能版本控制的工具，實際上，全球範圍內API服務領域中已經存在一些優秀的Web API設計工具。

如今，如EOLINKER、RAML、Swagger，都提供了出色的編輯工具來支持他們的語言。EOLINKER採用的是版本對比和重點標註提示，能夠清晰的切換、對比。RAML、Swagger採用的是版本切換，方便程度可能略遜一點。並且只有前者是支持中文的，後兩種只支持英文語言。這些API編輯器都能輕鬆地實現API版本的控制，使得更容易在更短的時間內切換運行版本。

附上EOLINKER的官方網址：https://www.eolinker.com

附上Swagger的官方網址：https://swagger.io/

附上RAML的官方網址：https://raml.org/

最後的想法

請記住，API是與你的消費者連接的樞紐。打破舊的鏈接，就須要新版本。選擇策略，制定計劃，並與API使用者溝通該計劃，這纔是版本控制的最終目的。

參考資料：James Higginbotham，When and How Do You Version Your API?

原文地址：https://dzone.com/articles/when-and-how-do-you-version-your-api