我在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/cust...。當技術限制阻止基於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?