變化是不可避免的，增長是一件好事。當您的API已經超出了最初的意圖和容量時，就該考慮下一個版本了。

無論下一次迭代是一個完整的版本升級還是一個功能擴展，重要的是要考慮你如何讓你的開發人員知道它的優缺點。與傳統的軟件版本控制相比，API版本控制可能會對下游使用它的產品產生復雜的影響。

較大的版本調整通常意味著API代碼庫中一個重要的里程碑。它聲明了API使用和實現需求的重大變化。不需要改變現有調用的特性添加是產品有機增長的一部分，不需要同樣的考慮。

一旦你開始刪除一些東西，或者戲劇性地改變現有的東西，就該考慮另一個版本了。通常，這些新版本會變成全新的產品。盡管它們共享一個共同的祖先，但是遺留api的新版本在實現時需要仔細考慮。

傳統的API版本控制:n+1

可以保證新版本的服務更改包括:刪除操作、重命名操作、移位數據類型或順序的操作參數更改，以及數據類型的復雜結構更改。

版本增量還可以指示API使用需求的重大變化。它還可以對API提供的底層資源進行徹底的更改。在任何一種情況下，依賴于API實現核心功能的產品和平臺都可能需要進行代碼重構來適應。

這可能會耗費大量的時間和資源，因此對于多個涉眾來說，使用一種合理且文檔記錄良好的URI版本控制方法是至關重要的。版本控制在團隊中可能是一個有爭議的話題，通常第一個問題就是是否使用它。

一個URI來統治所有的URI

一種思想是專注于一個不變的URI，只有一組消費標準。如果改變了API結構、改變了資源或修改了參數集，那么產品將使用相同的URI重新啟動。這就把重構代碼的責任推給了下游的開發人員。

蒂姆?伯納斯-李(Tim Berners-Lee)的名字被這種方法的支持者提到。他經常說:“一個酷的URI是不會改變的。”這句話的本意是要說明新興的互聯網依靠網頁內的超鏈接才能生存下去。互聯網絡在當時是一系列信息節點。

不過，世界已經改變了，我們使用的是一個相互連接的矩陣，它由功能強大、資源豐富的web服務組成。一旦服務變得廣泛，早期的方法類似于軟件版本號。但是，獨立軟件對下游的影響與相互依賴的web服務大不相同。

IBM在他們自己的“Web服務最佳實踐”中解決了這個問題:

正確處理API版本控制一直是分布式系統開發者面臨的最困難的問題之一。人們提出了各種各樣的方案，從CORBA(公共對象請求代理體系結構)采用的自由放任的方法，到DCOM中使用的更嚴格的方案(分布式組件對象模型)。隨著Web服務的出現，您可以利用一些新特性來幫助緩解問題，但殘酷的事實是，版本控制還沒有內置到Web服務體系結構中。”

什么是“最佳實踐”已經隨著時間的推移而演變，并由供應商對其自己產品的選擇決定，而不一定來自任何外部管理機構。因此，當涉及到選擇版本控制方法時，有各種各樣的實踐。

在向后兼容

另一個要考慮的問題是向后兼容性。對于許多web資源API的提供者來說，這是首要考慮的問題。維護一個資源密集型API的多個版本會嚴重消耗工程團隊的時間和精力。它還會給遷移到更現代體系結構的服務帶來長期的穩定性問題。

對許多人來說，引入一個實質上改變API的新版本實際上就是啟動一個全新的服務。將其作為一個新產品，使用新的文檔、服務水平協議、層訪問更改等，可能會產生重大的業務影響。許多白板上都寫滿了數字，爭論一個變化是工程選擇還是商業轉變。

一旦做出了引入新版本的決定，查看一下已建立的提供商，看看是否有經過測試的解決方案，這是很有幫助的。

更廣的進行版本控制的例子

我們可以從已建立的web API提供商的版本控制實踐中學到什么?谷歌從一開始就直截了當地肯定了編號版本化:“網絡API應該使用語義版本化。“沒有多少回旋余地。它們也有一個類似的平面系統。版本指示器使用v. major . min . patch形式。

Twilio在URL中使用了時間戳，而不是版本號。Salesforce選擇vXX.X在URL的中間。Facebook會將版本預先添加到端點路徑中。版本實際上是可選的，未指定的版本請求將被路由到最舊的可用版本。

請注意vX.X提供的粒度，vX.X通常用于開發，而不一定用于生產。首先檢查文檔，但是在生產代碼中選擇序號引用是一個好主意。

DevOps人員可能熟悉用于版本定義的UDDI和WDSL方法。HTTP解決方案要流行得多，但是有對這種方法的支持。它需要通過XML交換進行版本請求以獲得正確的版本。

像微軟、IBM和Oracle這樣的巨石公司在他們的一些文檔中都引用了這種方法。盡管，HTTP版本標識在許多部門和產品中被接受。

約會網絡Badoo選擇了持續的版本控制，即添加特性而端點保持不變。舊客戶端可以使用舊字段，新客戶端可以使用添加的字段。API請求是事務性的，發出一個特性請求調用并返回可用選項列表。特性檢查可以作為一種狀態請求。

API stylebook在版本控制方面還有其他一些方法可供探索。沒有一套成文的規范，公司繼續探索不同的選擇。

帶有Accept標頭的版本

路徑參數的一種常見替代方法是頭交換。它們可以更詳細地描述預期的響應，并且通常包含在HTTP請求中。使用特定于資源的頭方法允許包含其他參數(如緩存、壓縮和內容協商)。

API提供者通常在其響應中傳達資源標準和限制，因此開發人員無論如何都需要檢查header交換。除了響應代碼之外，常見的報頭響應還包括速率限制、特定的錯誤消息、基于時間的數據等等。

聰明的離群值使用MIME類型包含版本指示符。API提供者在其后端注冊這些MIME類型，然后用戶包括Accept頭和Content-type頭。IETF在RFC4627中合法化了這種方法。雖然這是可行的，但是選擇這種方法的開發人員最終將不可避免地向管理類型解釋他們的選擇，這些管理類型會說:“但是它不能在HTML表單上工作，那么為什么要這樣做呢?”

Accept: application/pre.company.app-v1+json Content-Type: application/pre.company.app-v1+json

關于實施的爭論是深刻的，并將繼續下去。因此，開發人員和供應商將不得不根據他們的具體需求做出選擇。通常，最常見的方法是URI參數和頭標準的組合。api接受帶有參數的URI請求，然后返回帶有適當響應代碼的有效負載，以及(希望如此)響應頭中的詳細元數據。

工程師們會在公司的歡樂時光里，興高采烈地大聲討論什么是合適的回應碼。但是，這里有一些有用的負面反應，它們冗長到足以對下游有所幫助。

400: BAD_REQUEST: ApiVersionUnspecified: An API version is required, but was not specified
400: BAD_REQUEST: InvalidApiVersion: An API version was specified, but it is invalid
400: BAD_REQUEST: AmbiguousApiVersion: An API version was specified multiple times with different values
400, 405: BAD_REQUEST, METHOD_NOT_ALLOWED: UnsupportedApiVersion: The specified API version is not supported
301: MOVED_PERMANENTLY: movedPermanently: This request and future requests for the same operation have to be sent to the URL specified in the Location header of this response instead of to the URL to which this request was sent
410: GONE: deleted: The request failed because the resource associated with the request has been deleted
299: OK: Warning: "Deprecated API"

業務動機將指導版本選擇

在某些方面，版本控制的技術方面是最容易解決的。真正的爭論歸結為產品需求、業務關注點和未來計劃。就工程支持、后端資源和簡單帶寬而言，支持一個API的多個版本的需求可能非常高。

另外，要想做得好，新版本需要豐富的文檔來成功地轉換。由于對快速發展的公司來說，最新的文檔往往沒有什么優先級，因此它可能會以新舊文檔的混搭而告終。糟糕的文檔會導致時間和金錢上的巨大損失。

這里的主要要點是版本控制是一個多方面的對話。這不僅僅是一個技術問題。下游影響和遺留成本可能是巨大的，為了有效增長，應該對整個過程進行仔細考慮。