落地開放銀行 - 深入開放API版本策略 | IDCF

來源：ThoughtWorks商業(yè)洞見

作者：肖然 

開放銀行雖然有多種對外連接方式，但API以其易用性成為了接受度最好的選擇，也是很多綜合性銀行推廣開放銀行必然需要對外提供的核心能力。

簡單的API之下，蘊藏著復雜的API支撐體系，不管是設計時的命名和路由規(guī)范，還是運行時的安全和容錯處理，深入細節(jié)都讓人生畏。

欣慰的是，隨著技術(shù)的持續(xù)演進，越來越多的經(jīng)驗被逐步提煉成了標準和工具，讓整個API的治理持續(xù)簡化。特別是在英國和新加坡政府主動推進開放銀行（Open Banking）之后，金融服務領域在API方面有了越來越多的資產(chǎn)可以為各家銀行所采用。

如果想體驗一下開放API為金融行業(yè)發(fā)展帶來的便利，可以參考《開發(fā)者體驗 – 開放銀行的奠基石》文中對行業(yè)領先者 —— 德意志銀行的分析。

（2021年，英國開放銀行組織慶祝成立3周年，https://www.openbanking.org.uk/）

然而API版本（Versioning）設計一直是開放平臺設計上的老大難問題。

就像過去幾十年支持了我們幾大行高速發(fā)展的主機系統(tǒng)，想要遷移到開放平臺，都是一次龐大的再造工程。而開放銀行本身的商業(yè)模式，又決定了API一旦發(fā)布，圍繞其生態(tài)的干系方是完全不由銀行控制的。很多銀行人都經(jīng)歷過系統(tǒng)報文格式的切換，切換過程中細枝末節(jié)的問題經(jīng)常造成大家挑燈夜戰(zhàn)。但報文本身畢竟還是同業(yè)圈子內(nèi)的升級，可控性較好，開放銀行卻是涉及到多元化異業(yè)的分布式協(xié)作，沒有任何一方有絕對的控制力。

API版本策略也很難要求各大銀行都完全一致，必然受制于各家開放業(yè)務想法的不同，和內(nèi)部系統(tǒng)架構(gòu)的架構(gòu)差異。所以具體采用什么策略實際上是一個業(yè)務和技術(shù)的綜合決策，而業(yè)務和技術(shù)在API版本策略上的對齊往往被大家忽略，結(jié)果就是業(yè)務認為加個接口字段很簡單，開發(fā)卻抱怨破壞了版本一致性，造成巨大的外部兼容性問題。

下面就讓我們從一個相對綜合的視角來研討一下開放API的版本模式，促進銀行業(yè)在開放API平臺建設方面更多碰撞和思考。

軟件版本 VS API版本

現(xiàn)代社會每個人都是軟件用戶，特別是在智能手機普及的今天，各種各樣的軟件已經(jīng)融入到了我們?nèi)粘Ｉ钪小?/span>對于軟件的“升級”是一件習以為常的事情，很多時候我們都會被提示軟件版本過低，需要升級才能使用某功能。

移動APP時代對于軟件版本管理實質(zhì)上是做了大量的簡化，不管是蘋果的iOS平臺，還是安卓Android平臺，APP軟件的版本都是一直向前升級的。如果突然打開一款久不使用的APP，提示版本太低不能使用，或者由于手機操作系統(tǒng)太老舊而無法使用新版本，我們都會覺得是常理之中的事情，不會有啥針對軟件開發(fā)者本身的抱怨。

甚至如果一款APP超過兩周都沒有任何改變，我們會懷疑其活躍程度，是不是背后老板已經(jīng)跑路了。APP軟件版本升級成了和服務一起演進的事情，服務越來越好、功能越來越多，自然要求發(fā)布新的軟件版本，比如雙十一前，各大電商肯定是要更新幾次自家APP的。

當然智能手機之外我們其實還有很多的大型商業(yè)軟件，比如每家企業(yè)現(xiàn)在都需要的財務管理軟件，這些軟件在市面上存在著多個版本，由于行業(yè)、規(guī)模、經(jīng)營各家企業(yè)都不盡相同，所以這樣的商業(yè)軟件用不同的版本適配不同的企業(yè)是很常見的。

這之上也有企業(yè)幾年前買了一個軟件版本，由于各種原因，一直使用沒有升級，也或許確實滿足了企業(yè)的需求，沒有必要采納新版本。版本本身在這樣的商業(yè)軟件交易時就是其中一個關鍵屬性，并且一般都有針對后續(xù)發(fā)布新版本是否采納方面的合同條款。

開放API版本兼具了以上兩種軟件的特點，但又提出了更高的要求。由于商業(yè)合作和生態(tài)的持續(xù)豐富，開放API顯然會持續(xù)升級，而且新的版本應該比舊的版本更加高效（不排除功能上有增加，比如訪問鑒權(quán)），常見的需求是過去1分鐘100筆交易，現(xiàn)在要求1萬筆。作為API的使用者，期待和更新手機APP一樣，新版本應該更強大。

不同于手機APP的是，開放API升級后不可能強行要求“用戶”升級，外部使用API的系統(tǒng)更新或改變都不是API發(fā)布者能掌控的，并且也不可能通過類似iOS這樣的平臺去統(tǒng)一使用要求，比如安全合規(guī)方面的統(tǒng)一升級。

開放API同時也是被多方使用的，和商業(yè)軟件一樣，最開始連接時采用的是當時的API版本，后續(xù)有的連接希望一直用下去，有的可能提出新的述求。當新的述求被新的API版本滿足后，作為之前的API使用者，我們會默認新版本不會破壞之前的服務，即使新功能對于部分使用者來說沒有采用。

商業(yè)軟件的世界里，我們經(jīng)常會聽到版本5.0是一個大升級，必須重新安裝，不支持從4.0升級。這時我們一般有些小懊惱，但卸載4.0，安裝5.0也不是太大的困難。然而如果某API的5.0版本不兼容4.0版本，也就意味著4.0的使用者們需要重新修改自己的系統(tǒng)，當我們有成百上千的外部應用使用該API時，這就是一個巨大的挑戰(zhàn)，很多時候甚至不得不面臨用戶的投訴。

API版本致勝原則

迎接這樣的挑戰(zhàn)，我們首先需要明確開放API版本升級的是什么？

首先API是用來傳遞信息的，信息顯然必須遵循一定的格式。銀行從業(yè)者立馬就能想到報文，比如全球通行的SWIFT報，每種報文必然需要有相關的字段設計和格式要求，信息的提供者和消費者都必須根據(jù)格式規(guī)范來，要不然就沒法交流了。當然這樣的格式調(diào)整最好少做，每次都帶來了巨大的工作量，收益卻有限。

（SWIFT報文示例，報文格式本身是信息傳遞的一部分。任何格式的改變都要求收發(fā)方必須同步，這對于面向開放的互聯(lián)網(wǎng)來說是不現(xiàn)實的）

報文的使用源自于電報時代的點對點信息溝通，卻不是我們這個互聯(lián)網(wǎng)時代所說的API。API提供的信息某種意義上是針對業(yè)務實體的操作，比如增刪查改（CRUD），API的命名其實就是要描述這樣的操作。這里我們不糾結(jié)于API采用的實現(xiàn)架構(gòu)（RESTful和RPC），專注于API版本背后的實質(zhì)，就會發(fā)現(xiàn)其實需要被管理的是業(yè)務實體的變化。

類比一下汽車制造商常用的版本控制方式，奔馳寶馬這樣的汽車制造商通常每4、5年推出新一代的流行車型，比如寶馬的X系列。接下來每年都會有升級版本，比如2019年的X1和2018年的X1性能不同，而且外形上也有稍許不同。每個客戶購買的汽車是特定型號的特定版本汽車，如果制造商召回汽車來修復故障，也需要明確型號和版本，當然后續(xù)維修是無法使您2018版本汽車的外觀及行為和2019年版本一樣的。

回到金融領域，我們的業(yè)務實體很多，比如某個客戶的某種賬戶、某種類型交易、債券衍生品等等。開放API提供了讓我們的合作伙伴能夠操作這些實體，比如客戶想通過第三方支付應用調(diào)轉(zhuǎn)自己賬戶里的存款。顯然我們不會把客戶賬戶的信息以報文的形式傳遞給第三方，API提供的是第三方在客戶提供授權(quán)信息的情況下，能夠告知我們將客戶的資金轉(zhuǎn)往哪個指定賬戶。

所以API版本的背后是我們業(yè)務實體的變化，比如由于監(jiān)管合規(guī)的要求，客戶賬戶需要進行更進一步的實名驗證，更多的信息需要采集和存儲，這就擴展了客戶賬戶這個實體的設計。

很顯然這樣的業(yè)務實體變化，在接下來金融服務開放普惠的主旋律下是不可避免的，這也是開放API平臺版本策略為什么是必須考慮的一個核心治理問題，好的開放API版本策略必然需要滿足以下兩大原則。

原則一：平臺獨立性

無論內(nèi)部如何實現(xiàn)API，任何客戶端都應該能夠按照發(fā)布的規(guī)則調(diào)用API。這就要求API使用開放的標準協(xié)議，并具有一種機制，讓客戶端和Web服務端可以就要交換的數(shù)據(jù)格式達成一致。在整個連接過程中，API提供方不關注客戶端使用方來自于什么平臺，即不因為偵測到iOS系統(tǒng)發(fā)來的請求，就提供不同于Android系統(tǒng)的處理和反饋。

互聯(lián)網(wǎng)幾十年的高速拓展實際上給我們提供了一整套基于HTTP協(xié)議的運作機制，而這套機制是我們推薦開放API設計者們?nèi)肀У摹Ｈ绻麑g覽器比作基于HTTP協(xié)議的Web操作系統(tǒng)，那任何的瀏覽器都需要實現(xiàn)相關的協(xié)議標準，從而能夠進行Web信息的請求和呈現(xiàn)。

原則二：服務兼容性

開放API應該能夠獨立于客戶端應用程序進行演化和添加功能。隨著API的發(fā)展，現(xiàn)有的客戶端應用程序應繼續(xù)運行而無需修改。而且所有功能，比如新的安全認證方式，都應該是可被發(fā)現(xiàn)的，以便客戶端應用程序可以充分使用它。

基于HTTP的RESTful架構(gòu)也給我們提供了很多處理兼容性的手段，超媒體（Hypermedia）的提出某種意義上就是為了解決網(wǎng)絡上開放接口請求兼容性問題而設計的。當然超媒體的引入會帶來整個接口設計、開發(fā)到運維成本的較大增長，所以在API設計上，針對不同的上下文（復雜度）也會有很多的處理方式。

一言以蔽之，開放API版本的致勝之道就是讓使用方感覺“沒有版本”，客戶端從設計、開發(fā)，到發(fā)布、運營都不會因為某個API的升級而出現(xiàn)服務中斷。

主流API版本模式

我們談開放API的基礎環(huán)境是互聯(lián)網(wǎng)，所以HTTP毫無疑問是必須采用的協(xié)議。如前文提到，在版本策略設計上，希望盡量不要耦合于特定的實現(xiàn)模式，雖然RESTful是我們推薦的實現(xiàn)方式，但也理解在一些場景下設計者會傾向于描述更為直接的WebSocket模式。

（有能力的銀行也可以效仿亞馬遜AWS提供兩套實現(xiàn)架構(gòu)，便于使用者根據(jù)自身場景靈活選用。https://aws.amazon.com/cn/api-gateway/） 

基于開放API的致勝原則，在處理版本升級挑戰(zhàn)上，我們認為有以下四種常見模式供大家參考。每種模式并非是完全獨立的，很多時候我們看到不少開放API平臺也動態(tài)采用著多種模式。

模式一：頭文件定制版本字段

由于HTTP協(xié)議頭文件里允許定制字段的擴展，我們可以采用 “X-MyAPIVersionRequest-Header: 2.0” 這樣的方式來表達請求的myapi是版本2.0。

假設針對客戶賬戶支付的一個開放API，1.0版本主要是針對同業(yè)的銀行合作伙伴，希望在2.0支持持牌的金融科技公司。針對金融科技公司我們需要做額外的風控和限額，那么就可以要求金融科技企業(yè)的客戶端在API請求中必須包含這樣一個擴展的版本頭文件字段。未來也可以針對更多的客群，比如小微商戶，發(fā)布3.0、4.0，通過版本來明確針對同一業(yè)務實體，同一操作的不同步驟。

由于是定制字段，使用方在設計自身的客戶端調(diào)用時，是需要理解游戲規(guī)則的。對于API提供方來說做到了較好的兼容性，但擴展性卻受到了一定的制約，畢竟定制化知識的傳播成本是遠高于通用型標準的。

模式二：媒體類型擴展版本信息

同樣是利用HTTP協(xié)議頭文件中的接受請求媒體類型進行拓展，我們可以要求“Accept: application/x.myapi+json;version=2.0” 這樣的方式來指定請求myapi的第二個版本。

對比第一種定制化字段的方式，這種模式利用了已有的HTTP頭文件字段。比較好的適用于擁有默認版本選擇的API，比如客戶賬戶支付操作如果在不指定版本的情況下就走最嚴格的檢查步驟（對應的版本），而一些特定機構(gòu)可以走其它版本來簡化步驟，以提高清算效率。

這種擴展已有字段的模式也存在比較明顯的問題，這些字段的解析有可能已經(jīng)被現(xiàn)有的客戶端按照標準方式進行了解析和利用。比如針對媒體類型，很可能客戶端進行了不同的緩存策略來提升用戶體驗，這樣的改變將會讓基于標準字段的客戶端實現(xiàn)無法應用。

模式三：路由設計版本路徑

通過HTTP定位API和Web資源都需要通過URI，很自然我們也可以在URI上加入版本信息，比如“/v2/myapi”，通過路由來識別請求的具體API版本。

如果一個API有多個差異較大版本，那么我們可能就會有“/v3/myapi”、“/v4/myapi”等一系列URI。從客戶端視角，由于路由不同，所以其實可以認為每個版本都產(chǎn)生了一個新的API。

這種設計雖然保證了兼容性，但新的功能實際上并沒有提供給已有使用者，想用新功能還是需要客戶端的改變。而且新版本增加了API的數(shù)量，提高了整體運營成本。

模式四：請求參數(shù)版本字段

通過HTTP請求資源也允許在URL中帶參數(shù)，利用這個特性我們可以傳遞希望請求的API版本，比如“/myapi?version=2”。

這種方式的可讀性很好，也遵循HTTP的默認標準，對于API設計者來說比較容易實現(xiàn)，但存在實際運營過程中的挑戰(zhàn)，特別是多層級API調(diào)用在路由過程中參數(shù)傳遞的問題，某種意義上會破壞兼容性。在一些通過API網(wǎng)關進行重定向的時候，由于路由系統(tǒng)不知道參數(shù)的意義，有可能從安全角度自動消除，造成請求真正到達服務側(cè)時參數(shù)丟失。

以上四種常見模式實際上各自有不同的適用性場景，因此很難說API版本策略一定是采用哪種模式。比如當“破壞性”改變發(fā)生在某一個業(yè)務實體之上時，采用顯式版本路由來明確調(diào)用的API版本就可能是最佳方式；而僅僅是為客戶端可以采用更好的緩存技術(shù)來提高用戶體驗的版本改進，可能采用頭文件中的字段來標注版本就是合適的。

API版本演進策略

讀到這里，大家可能會認為必須在發(fā)布第一個API版本之前定義版本控制策略，否則后續(xù)API改變將會面臨巨大的挑戰(zhàn)。事實卻并非如此，能夠真正幫助大家迎戰(zhàn)API版本挑戰(zhàn)的是策略上的靈活，根據(jù)具體業(yè)務上下文選擇合適的版本模式。

延遲決策可能是件好事情

我們都清楚現(xiàn)在軟件和系統(tǒng)所面臨的業(yè)務不確定性，一開始很難預期接下來針對業(yè)務實體的變化，比如當下沒有人可以預言未來兩年數(shù)字貨幣帶來的新需求和新功能是什么樣子的。而駕馭這樣的不確定性其中的一條黃金定律就是“延遲決策”，在遵循了良好開放API設計規(guī)范的基礎之上，形成良好的業(yè)務和技術(shù)合作，就能夠針對每個開放API保留未來改變的靈活性。

解耦每項API治理工作

開放API本身是一個復雜系統(tǒng)，這里我們僅僅是談了版本管理的挑戰(zhàn)，如果加入注冊發(fā)現(xiàn)等機制，我們會發(fā)現(xiàn)確實會互相影響，進而讓策略討論變得異常復雜。我們的建議仍然是保持這些關注點的分離，解耦各項治理工作，不要在一項治理策略中引入針對另外幾項的依賴，比如版本策略的工作必須依賴于注冊機制采用某種特定模式。一旦開始關聯(lián)這些工作，我們就很難設計出真正意義上簡單的解決方案。而我們都知道在開放的互聯(lián)網(wǎng)生態(tài)中，唯有簡單才能夠持久，唯有包容才能夠生存。

2021 IDCF 公開課招生ing

2021年《IDCF DevOps黑客馬拉松》北京、深圳、上海站開啟，還有《端到端DevOps持續(xù)交付（5P）工作坊》、《基于Boat House的DevOps實踐》、《“創(chuàng)新設計思維/Design Thinking”工作坊》、《敏捷項目管理實戰(zhàn)沙盤演練》等眾多公開課可以參加，快快報名吧~