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

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

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

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

傳統(tǒng)的API版本控制:n+1

可以保證新版本的服務(wù)更改包括:刪除操作、重命名操作、移位數(shù)據(jù)類型或順序的操作參數(shù)更改，以及數(shù)據(jù)類型的復(fù)雜結(jié)構(gòu)更改。

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

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

一個URI來統(tǒng)治所有的URI

一種思想是專注于一個不變的URI，只有一組消費標(biāo)準(zhǔn)。如果改變了API結(jié)構(gòu)、改變了資源或修改了參數(shù)集，那么產(chǎn)品將使用相同的URI重新啟動。這就把重構(gòu)代碼的責(zé)任推給了下游的開發(fā)人員。

蒂姆?伯納斯-李(Tim Berners-Lee)的名字被這種方法的支持者提到。他經(jīng)常說:“一個酷的URI是不會改變的?！边@句話的本意是要說明新興的互聯(lián)網(wǎng)依靠網(wǎng)頁內(nèi)的超鏈接才能生存下去?；ヂ?lián)網(wǎng)絡(luò)在當(dāng)時是一系列信息節(jié)點。

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

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

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

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

在向后兼容

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

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

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

更廣的進(jìn)行版本控制的例子

我們可以從已建立的web API提供商的版本控制實踐中學(xué)到什么?谷歌從一開始就直截了當(dāng)?shù)乜隙司幪柊姹净?“網(wǎng)絡(luò)API應(yīng)該使用語義版本化?！皼]有多少回旋余地。它們也有一個類似的平面系統(tǒng)。版本指示器使用v. major . min . patch形式。

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

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

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

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

約會網(wǎng)絡(luò)Badoo選擇了持續(xù)的版本控制，即添加特性而端點保持不變。舊客戶端可以使用舊字段，新客戶端可以使用添加的字段。API請求是事務(wù)性的，發(fā)出一個特性請求調(diào)用并返回可用選項列表。特性檢查可以作為一種狀態(tài)請求。

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

帶有Accept標(biāo)頭的版本

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

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

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

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

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

工程師們會在公司的歡樂時光里，興高采烈地大聲討論什么是合適的回應(yīng)碼。但是，這里有一些有用的負(fù)面反應(yīng)，它們?nèi)唛L到足以對下游有所幫助。

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"

業(yè)務(wù)動機(jī)將指導(dǎo)版本選擇

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

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

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