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

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

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

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

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

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

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

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

一個(gè)URI來(lái)統(tǒng)治所有的URI

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

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

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

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

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

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

在向后兼容

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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ù)動(dòng)機(jī)將指導(dǎo)版本選擇

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

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

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