[[279233]]

API 是模塊或者子系統(tǒng)之間交互的接口定義。好的系統(tǒng)架構(gòu)離不開好的 API 設(shè)計(jì)，而一個設(shè)計(jì)不夠完善的 API 則注定會導(dǎo)致系統(tǒng)的后續(xù)發(fā)展和維護(hù)非常困難。比較好的API設(shè)計(jì)樣板可以參考 github 和 k8s ，它們都是典型的RESTful接口。云服務(wù)對外開放的窗口就是OpenAPI，今天要討論的話題是“云服務(wù)場景下OpenAPI設(shè)計(jì)的挑戰(zhàn)”。

為什么要有API規(guī)范

之所以強(qiáng)調(diào)“云服務(wù)”的原因在于，小規(guī)模獨(dú)立API的設(shè)計(jì)與大規(guī)模批量生產(chǎn)API面臨的問題是不一樣的。同樣，只專注于自身產(chǎn)品API的可用性與從更高的層次去看云服務(wù)整體API體系的健壯性，要建設(shè)的體系也是不一樣的。

例如，做一個WEB頁面使用的API，只需要考慮性能、穩(wěn)定性、鑒權(quán)就好，因?yàn)轫撁媾cAPI是一體的，可以一起發(fā)布和回滾，只要功能正常，即便API設(shè)計(jì)有缺陷，用戶也可以接受。而云服務(wù)要開放API考慮問題就多了：

• 首先，云服務(wù)開放的是基礎(chǔ)設(shè)施和服務(wù)接口，一般是系統(tǒng)級的對接，API一旦開放想要變更就非常困難;
• 其次，云服務(wù)并非單獨(dú)運(yùn)行，不同的產(chǎn)品實(shí)際場景中是互相組合的，需考慮產(chǎn)品間的一致性和互通便利性;
• 云服務(wù)API數(shù)量龐大，為了更方便使用，配套的API查找、編排、自動化生成SDK等需求也比普通服務(wù)強(qiáng)烈;
• 云服務(wù)的穩(wěn)定性非常重要，核心產(chǎn)品的穩(wěn)定性就是客戶的生命線，要求非常高。

所以云服務(wù)由于產(chǎn)品線眾多，需要統(tǒng)一的API規(guī)范來保證云產(chǎn)品間API體驗(yàn)一致，在底層平臺層面互相兼容，便于上層應(yīng)用平臺化，同時要兼顧到圍繞公有云服務(wù)的第三方生態(tài)、開源生態(tài)、企業(yè)生態(tài)。

在具體規(guī)范層面，業(yè)界也在不斷嘗試，比較知名的是OpenAPI Specfication和 Google API Design Guide。前者針對RESTful API設(shè)計(jì)在細(xì)節(jié)層面給出了非常具體的規(guī)定，已經(jīng)成為RESTful API設(shè)計(jì)領(lǐng)域的事實(shí)標(biāo)準(zhǔn)，而后者則主要從云廠商的角度提出許多最佳實(shí)踐性質(zhì)的規(guī)范與建議，這些原則不僅僅適用于RESTful API，也適合其他類型API設(shè)計(jì)。對API設(shè)計(jì)感興趣的開發(fā)者，可以詳細(xì)研究一下資料。

[[279234]]

2018年Openapi Specification發(fā)布了3.0版本

圖片來源：https://swagger.io/

因此，對于云服務(wù)商來說，在關(guān)鍵環(huán)節(jié)制定明確的API規(guī)范有助于云服務(wù)對內(nèi)提高產(chǎn)品間互通的效率，對外提供一致的使用體驗(yàn)，有助于云服務(wù)更好地被集成。那么要做好云服務(wù)的橫向規(guī)范會碰到哪些困難呢?本文就從實(shí)踐中總結(jié)了7大挑戰(zhàn)。

挑戰(zhàn)1：選擇API設(shè)計(jì)模式

當(dāng)你在考慮單個產(chǎn)品的API表現(xiàn)形式時，首先會選擇一種具體的API風(fēng)格，常見的有RPC(Remote Procedure Call)和ROA(the Rest-Oriented Architecture)兩種模式，然后針對復(fù)雜的數(shù)據(jù)結(jié)構(gòu)你會考慮使用什么樣的序列化協(xié)議，常見的包括Json/Xml/WSDL/Hessian等，用于封裝傳輸數(shù)據(jù)。但涉及到不同的產(chǎn)品時，在具體選型時考慮的問題可能就不太一樣了。

gRPC示意圖

圖片來源：https://www.grpc.io/docs/guides/

雖然RESTful設(shè)計(jì)風(fēng)格曝光率很高，但并不是所有云服務(wù)商都選擇了完全遵循RESTful，例如AWS和阿里云RPC風(fēng)格反而占了大多數(shù)，Google和Azure則RESTful居多。

Restful API的優(yōu)勢是HTTP具備更好的易用性，讓異構(gòu)系統(tǒng)更容易集成，且開發(fā)執(zhí)行效率比較高，面向資源要求也比較高。而RPC API可以使用更廣泛的框架和方案，技術(shù)層面更底層也更為靈活，設(shè)計(jì)起來相對簡單，掌握起來有一定門檻，架構(gòu)上更加復(fù)雜。

RESTful與RPC模式對比

不同的團(tuán)隊(duì)根據(jù)實(shí)際情況和業(yè)務(wù)形態(tài)可能選擇不同的方案，那云服務(wù)作為一個整體應(yīng)該強(qiáng)制統(tǒng)一好還是隨意選擇好?如果強(qiáng)制統(tǒng)一風(fēng)格，有些適合RESTful風(fēng)格的服務(wù)非要使用RPC的話，看起來就會比較丑陋，如果只是一個過程化的服務(wù)調(diào)用，往RESTful資源化設(shè)計(jì)方向去靠會比較困難。但如果不強(qiáng)制使用統(tǒng)一風(fēng)格，會造成針對API的體系化支持會更加復(fù)雜，例如為兼容兩種風(fēng)格SDK的自動化支持需要兩套代碼。

通常RESTful風(fēng)格對API設(shè)計(jì)者的要求是比較高的，主要的難點(diǎn)在于面向資源設(shè)計(jì)要求開發(fā)者事先做好規(guī)劃，將后端數(shù)據(jù)模型與API服務(wù)模型相匹配。所以RESTful API的開發(fā)者應(yīng)該是熟知系統(tǒng)整體實(shí)體關(guān)系模型的，很難想象一個不懂后臺業(yè)務(wù)的新手能設(shè)計(jì)出合理的API來。那么是不是RPC風(fēng)格API就不需要面向資源設(shè)計(jì)了呢?從實(shí)踐中來看，并不是!RPC風(fēng)格的API也需要資源模型來支持，在下一節(jié)中會重點(diǎn)分析。

所以，對于云服務(wù)商來說，選擇API風(fēng)格時要考慮幾個問題：

• 選擇支持哪種風(fēng)格，才能更好地體現(xiàn)業(yè)務(wù)特性，讓客戶操作起來更加方便;
• 設(shè)計(jì)API時能否面向資源設(shè)計(jì)，相應(yīng)的工程人員是否具備做這種設(shè)計(jì)的能力;
• 針對這種風(fēng)格工具鏈的支持是否到位，投入產(chǎn)出比如何;
• 業(yè)界流行的趨勢如何，是否需要考慮與其他系統(tǒng)體系的互操作。

選定了具體設(shè)計(jì)模式后，就要努力做到統(tǒng)一，避免多種模式混雜帶來管理成本的上升。如果確實(shí)有必要兩種方式都支持(例如阿里云就同時支持RPC和ROA)，就需要在技術(shù)上做好充分的準(zhǔn)備。

挑戰(zhàn)2：面向資源設(shè)計(jì)API

用戶使用API來訪問云服務(wù)，本質(zhì)上是想通過對某種云資源執(zhí)行特定的操作來完成一個業(yè)務(wù)動作。Restful API需要面向資源設(shè)計(jì)眾所周知，那為什么RPC接口在云服務(wù)場景下也需要有資源模型呢?

RPC形式的API組織形態(tài)是領(lǐng)域和行為(對象和方法)，隨著時間的推移，API越來越多最終形成一個龐大的集合。以阿里云為例，對外開放的OpenAPI數(shù)量已經(jīng)達(dá)到10000多個，涵蓋了接近200個不同的產(chǎn)品。因?yàn)殚_發(fā)者必須單獨(dú)學(xué)習(xí)每個API，耗時又容易出錯，如果沒有一個脈絡(luò)的理解起來比較困難。如果有一套標(biāo)準(zhǔn)的資源模型，API就可以按照資源模型的維度分類組織，用戶使用起來也會有跡可循，體驗(yàn)上會更好，否則面對如此多的API一點(diǎn)點(diǎn)學(xué)習(xí)無疑是個痛苦的過程。

另外，云服務(wù)并非單個服務(wù)的簡單排列，它是多個體系的橫向整合，總體對外呈現(xiàn)出有機(jī)連接。隨著云計(jì)算的發(fā)展，企業(yè)客戶對對云服務(wù)的要求不斷提高。最典型的就是當(dāng)企業(yè)客戶大規(guī)模開始上云后，對虛擬化的云產(chǎn)品提出了各種管理需求，例如鑒權(quán)、編排、彈性伸縮等。

企業(yè)客戶對云服務(wù)的管理需求

以最常用的鑒權(quán)功能為例，客戶創(chuàng)建了一組云服務(wù)器來跑業(yè)務(wù)，運(yùn)維人員需要有重啟服務(wù)器的權(quán)限，其他角色人員則不需要此類權(quán)限，針對RestartServer這么一個API就需要進(jìn)行權(quán)限控制了。權(quán)限在云平臺中一般是中心式管理的，單獨(dú)的云產(chǎn)品不需要分別管理。如果統(tǒng)一處理鑒權(quán)，就需要知道當(dāng)前API正在操作什么資源，與此相關(guān)的資源有哪些(例如與服務(wù)器有關(guān)的資源包括磁盤、網(wǎng)卡、網(wǎng)絡(luò)等關(guān)聯(lián)資源)，然后針對所有相關(guān)資源逐一鑒權(quán)才能確認(rèn)API操作是否可行。

上面提到的資源有兩個關(guān)鍵點(diǎn)，一是要有統(tǒng)一的資源模型，便于云產(chǎn)品對特定的API進(jìn)行鑒權(quán)，二是要明確資源關(guān)系，當(dāng)出現(xiàn)資源依賴的時候，需要關(guān)聯(lián)鑒權(quán)。在Google的API Guide中就明確提到需要資源關(guān)系，可以看出資源關(guān)系不僅僅是用來做API設(shè)計(jì)建模的，它對于平臺功能的實(shí)現(xiàn)也有至關(guān)重要的作用。不了解資源關(guān)系，有可能把多個資源封裝到一個API中，使用和變更都很痛苦，即便后期發(fā)現(xiàn)了問題再補(bǔ)救拆開，由于很多用戶已經(jīng)在使用了，要付出的開發(fā)成本和溝通成本也是極大的，甚至成為不可能。所以清晰的資源模型有利于梳理清楚API體系。

定義清晰的實(shí)體關(guān)系圖有助于設(shè)計(jì)出更為完整的API

而且，明確的資源模型對于構(gòu)建云上運(yùn)維管理基礎(chǔ)設(shè)施至關(guān)重要，例如可以通過對資源打Tag來對資源進(jìn)行分類管理(參考阿里云資源Tag)，分組授權(quán)(參考阿里云資源組)，資源審計(jì)(參考阿里云CloudConfig)，類似開源軟件Terraform這樣的編排工具，由于有資源模型會更容易接入和使用。

所以，統(tǒng)一的資源模型對云服務(wù)的幫助是巨大的：

• 它可以使API具有更清晰的結(jié)構(gòu)，幫助用戶理解;
• 它可以幫助對比API與后臺實(shí)體關(guān)系模型，更容易提供更完整的API服務(wù);
• 它可以使產(chǎn)品協(xié)作更加順暢，對資源的操作也更加規(guī)范化;
• 它可以使云服務(wù)底層平臺實(shí)現(xiàn)起來更統(tǒng)一、更方便;
• 它可以使圍繞API的生態(tài)集成起來更加簡單、高效。

既然有這么多好處，那么眾多的云產(chǎn)品在實(shí)際設(shè)計(jì)API的時候能否堅(jiān)持以資源為中心，充分考慮到上下游的需求就變成一個很大的挑戰(zhàn)了。

挑戰(zhàn)3：API設(shè)計(jì)風(fēng)格

確定了設(shè)計(jì)模式和資源模型后，是時候進(jìn)入到API設(shè)計(jì)細(xì)節(jié)了。諸如API名稱、參數(shù)名、屬性名稱、數(shù)據(jù)格式、錯誤碼之類的信息，看起來根本不是問題。單個產(chǎn)品問題還不大，只要保證內(nèi)部風(fēng)格一致即可，如果考慮到云服務(wù)多產(chǎn)品對外的整體體驗(yàn)，就有必要考慮以下問題：

• 在API命名的時候，遵循什么樣的范式來確保大體風(fēng)格相似?動詞、名詞、介詞如何組合才能保持API風(fēng)格看起來比較統(tǒng)一，降低理解成本?
• 對于類似的操作，有沒有使用規(guī)范?有哪些公共的標(biāo)準(zhǔn)詞匯使得同類型的操作可以比較容易理解，避免使用晦澀奇怪的詞匯(例如讀操作，Read/Query/Describe/List/Get中都在什么場合使用什么動詞)?
• 被廣泛使用的參數(shù)如何盡可能保持一致，避免不同產(chǎn)品的表達(dá)混亂的情況(例如分頁參數(shù)用PageNumber還是PageNum)?
• 對于常用的場景，例如冪等、分頁、異步API的設(shè)計(jì)有沒有統(tǒng)一的規(guī)范，避免使用體驗(yàn)不一致?
• 錯誤碼應(yīng)該怎么設(shè)計(jì)?公共錯誤碼怎么統(tǒng)一，業(yè)務(wù)錯誤碼怎么表達(dá)?

上述問題都是實(shí)際研發(fā)過程中要注意的，要全部羅列的話遠(yuǎn)不止這些。API的用詞描述是云服務(wù)展現(xiàn)給外部用戶的第一印象，絕非隨意寫就。對人員有一定規(guī)模，內(nèi)部有多條產(chǎn)品線的組織來說，如何協(xié)調(diào)組織的各個部分對外具有統(tǒng)一的體驗(yàn)是個很大挑戰(zhàn)。

回顧下HTTP協(xié)議，最廣為認(rèn)知的是對HTTP Mehod的約定，使用9個單詞就完成了對基本動作的規(guī)范，為開發(fā)者提供了清晰的思維模型：

Http Method 類型

圖片來源：https://tools.ietf.org/html/rfc7231

同樣，在HTTP Header里面也對瀏覽器信息、語言、網(wǎng)絡(luò)連接屬性等做了詳細(xì)的規(guī)定，這樣開發(fā)者在使用HTTP服務(wù)的時候都有一個大致的約定，在關(guān)鍵信息上面不會有偏差，保障了異構(gòu)系統(tǒng)的接口一致性。

因此云服務(wù)在管理API時應(yīng)該考慮一些具體的規(guī)范，對命名規(guī)則、標(biāo)準(zhǔn)詞匯、最佳實(shí)踐模式、錯誤碼等信息都有明確的規(guī)定，同時用系統(tǒng)化、平臺化的手段來管理API，確保不走偏。設(shè)計(jì)風(fēng)格不是云服務(wù)API設(shè)計(jì)中致命的問題，但是它關(guān)乎云服務(wù)外表形象，不可不察。

挑戰(zhàn)4：服務(wù)端容錯處理

API是后端服務(wù)的外部表達(dá)，是服務(wù)就有可能出現(xiàn)問題，無論這個問題是可預(yù)期的還是不可預(yù)期的。如果只考慮功能本身功能特性，而忽視對異常情況的設(shè)計(jì)，當(dāng)問題出現(xiàn)的時候業(yè)務(wù)本身可能無法感知造成服務(wù)異常，更重要的是站在客戶角度去看，不能有效獲取錯誤原因是非常痛苦的，很多時候只能束手無策，降低云服務(wù)提供商的整體口碑，甚至損害營收。

假設(shè)有個創(chuàng)建資源的API，每調(diào)用一次都會創(chuàng)建新的資源，考慮以下情況：

• 同樣的請求多次提交，是否會重復(fù)創(chuàng)建資源?
• 請求處理時間過長，客戶端是長時間等待，還是先異步返回一個任務(wù)ID?
• 如果需要等待，Timeout最大值是多少?
• 如果Timeout最大值達(dá)到，客戶端的策略是重試還是放棄
• 如果最終處理還是失敗了，具體是哪個環(huán)節(jié)的問題?如何給出準(zhǔn)確的錯誤信息?
• 如果異步方式，異步處理完成后是主動查詢還是另有通知?
• 第三方工具和集成商到哪里去獲取這些信息?能不能有標(biāo)準(zhǔn)化的處理?

實(shí)踐中，如果不做好問題a的處理，可能會造成系統(tǒng)異常情況下大批資源被重復(fù)創(chuàng)建，有可能造成用戶或云服務(wù)商資損;問題b-e沒有處理好，可能會讓用戶陷入盲目等待或者盲目重試，使用體驗(yàn)和效率極差;而f-g關(guān)系到自動化處理工具如何做到效率最大化，也關(guān)系到被集成的效率。

一個異步重試的狀態(tài)機(jī)

當(dāng)出現(xiàn)異常的時候，API一般是要靠錯誤碼來告知用戶有什么問題。HTTP協(xié)議本身對錯誤碼做出了詳盡的規(guī)定，Restful的API要盡可能地符合標(biāo)準(zhǔn)。除此之外，云服務(wù)有必要在此基礎(chǔ)上進(jìn)一步提供業(yè)務(wù)錯誤碼和錯誤信息，來描述錯誤具體的細(xì)節(jié)。

當(dāng)前云服務(wù)的錯誤碼很多，看起來非常專業(yè)，但問題主要集中在以下幾個方面：

1.錯誤類型過多：錯誤碼越多客戶端處理起來越方便嗎?看一下HTTP的錯誤碼，只有5大類加幾十個子類的錯誤碼就涵蓋了所有場景，而通常大家耳熟能詳?shù)臒o非是200、400、404、500、502等屈指可數(shù)的狀態(tài)碼。有的人考慮錯誤碼越多，客戶端可以switch/case一下針對每個錯誤碼做不同的操作，這個就見仁見智了，一般的程序員可能不會寫那么多的分支流程，必要性也不大。

2.錯誤信息表達(dá)不夠充分：相比于提供大量的錯誤碼，錯誤信息的明確表達(dá)更為重要。如果錯誤信息不夠詳細(xì)，作為用戶不了解細(xì)節(jié)無法掌控的云服務(wù)，幾乎是無法明確發(fā)生了什么，要么提工單，要么只能被動等待，客戶體驗(yàn)很差。

3.業(yè)務(wù)錯誤碼與HTTP錯誤碼含義不匹配：例如參數(shù)錯誤應(yīng)該返回4xx系列Code，返回5xx系列就不夠?qū)I(yè)。即便是RPC風(fēng)格的API，也要大致符合HTTP規(guī)則，否則可能會給一些依賴HTTP Code的系統(tǒng)造成誤導(dǎo)。網(wǎng)上有種思路覺得無論后臺響應(yīng)如何，HTTP Code統(tǒng)統(tǒng)返回200，在Body里面的錯誤信息體現(xiàn)異常信息，這種不利于對接口的監(jiān)控，因?yàn)楸O(jiān)控系統(tǒng)很難通過識別消息體來鑒別功能是否正常響應(yīng)。

4.相同錯誤不同云產(chǎn)品表達(dá)不一致：這會給客戶端開發(fā)造成困擾，增加開發(fā)工作量，不利于自動化集成，用戶體驗(yàn)比較差。

5.錯誤碼應(yīng)該是可枚舉集合：一個API能夠產(chǎn)生的錯誤碼類型應(yīng)該是可預(yù)期的，即便是業(yè)務(wù)升級，也應(yīng)該給客戶提供明確的錯誤碼列表，不能隨心所欲。因?yàn)橛脩舳诵枰鞔_知道可能會發(fā)生什么，而不是隨時可能出現(xiàn)不可預(yù)知的錯誤類型。如果錯誤類型不確定，就意味著針對錯誤碼分支處理基本是無效的。

要做好服務(wù)端容錯上述問題，需要從云服務(wù)整體層面加強(qiáng)API的容錯設(shè)計(jì)，做好錯誤碼規(guī)范，加強(qiáng)對錯誤信息的管理，來提升用戶體驗(yàn)。

挑戰(zhàn)5：版本管理

API都是不斷迭代的，通常都需要版本管理。云服務(wù)API的版本管理尤其重要，主要是以下原因：

• 云服務(wù)API直接面向用戶，由于調(diào)用量大，變更影響的用戶范圍也更廣，版本變更要非常謹(jǐn)慎;
• 云服務(wù)有多種形態(tài)，主要是公有云、私有云、細(xì)分的行業(yè)云等，不同的云對同樣功能API的要求可能不一樣，API更加多樣化。既要保障不同版本功能正常，又要能快速部署維護(hù)不同版本，挑戰(zhàn)很大;
• 不兼容變更的推廣極其困難，很難讓用戶在短時間內(nèi)快速升級，維護(hù)多版本API成本很高;
• 必須變更的情況，要確保調(diào)用方能夠及時感知并且平滑切換的技術(shù)難度很大。

針對API各種場景的管理，需要一套成熟的API管理平臺，照顧到各種場景的需求，也是一項(xiàng)不小的挑戰(zhàn)。

挑戰(zhàn)6：API該如何開放

API如何開放看起來是奇怪的問題，難道API做出來不就是開放給別人用的嗎?做好就開放就開放啊?但在云服務(wù)場景下，情況會更復(fù)雜一點(diǎn)!

產(chǎn)品技術(shù)都是在不斷迭代的，功能始終在增加，新的API層出不窮。從客戶視角來看，他們對已開發(fā)完畢的API是否開放的需求是什么?假設(shè)一個云產(chǎn)品有100個功能特性，20個只能保留在內(nèi)部，官網(wǎng)上總共提供了80個特性，而公開API只開放了50個，這是用戶期望的狀態(tài)嗎?理想狀態(tài)應(yīng)該是什么?

圍繞云服務(wù)有一個龐大的生態(tài)，除了普通的開發(fā)者，還有許多第三方服務(wù)商、企業(yè)客戶、開源工具。當(dāng)我們考慮所有這些生態(tài)成員的需求時會發(fā)現(xiàn)：云服務(wù)自身擁有的功能集合與客戶能使用的功能集合之間的差異比較能體現(xiàn)產(chǎn)品的開放程度。這里的差異強(qiáng)調(diào)的是云服務(wù)已經(jīng)擁有的，不包括云服務(wù)自身沒有的服務(wù)。客戶能使用的功能與云服務(wù)能提供的功能之間的差距越大，說明云產(chǎn)品的開放程度越低，因?yàn)楹芏喙δ芏甲鳛楸Ａ艄?jié)目被雪藏了，導(dǎo)致客戶和第三方服務(wù)商無法享受與云廠商接近的服務(wù)，最終生態(tài)無法拓展。理想狀況是，云服務(wù)商自身能通過API使用的功能，客戶都能通過OpenAPI使用，內(nèi)外看到的是一致的。

但具體到某個API應(yīng)不應(yīng)該開放，實(shí)踐中會做如下考慮：

• API剛剛上線尚未打磨充分，貿(mào)然開放可能會留下隱患，再想調(diào)整為時已晚，所以選擇先不開放。
• API本身并非原子化，封裝了若干業(yè)務(wù)場景，主要目的是優(yōu)化性能或者服務(wù)特定的客戶，并不需要開放給所有用戶;而且當(dāng)業(yè)務(wù)場景發(fā)生變化的時候，調(diào)整起來也比較困難，不適合開放出去。
• 某些API不適合開放給全部用戶，只能部分開放，例如特定行業(yè)專業(yè)的API。
• API僅供特定場景或私有場景使用，需要外部能夠訪問，但是不能開放給用戶。

針對這些問題，需要在API的管理機(jī)制上面下功夫，能夠區(qū)分不同的場景，并做好元數(shù)據(jù)的管理。針對API是否開放要有明確的規(guī)范和度量機(jī)制，確保該開放的API都可以開放，確保內(nèi)外客戶看到的功能集合基本一致，才有利于云服務(wù)更好地被集成，在客戶的業(yè)務(wù)中發(fā)揮更大的作用。

挑戰(zhàn)7：API體系如何打通

在云服務(wù)場景中，API并非孤立存在：

首先，API發(fā)布以后，用戶要想順利地使用API，配套設(shè)施必不可少，SDK、文檔、工具鏈的集成都需要考慮到，這里的重點(diǎn)是如何保障準(zhǔn)確性、及時性和一致性。開發(fā)工程師一般都不太喜歡寫文檔，專業(yè)寫文檔的又可能不太懂技術(shù)，再考慮到國際化的問題，就十分有挑戰(zhàn)了。SDK方面，一個API要有多種語言的實(shí)現(xiàn)，每種語言還要保障其專業(yè)性、可用性，非?？简?yàn)對開發(fā)人員編程語言掌握的深度和對API的理解，業(yè)界經(jīng)常采用的自動化生成SDK的方式也會考驗(yàn)對多語言的兼容能力。工具鏈比如阿里云的 API Explorer、CloudShell等產(chǎn)品也需要及時與API的最新狀態(tài)保持同步。

其次，云服務(wù)由于產(chǎn)品線眾多，如何讓用戶能夠快速學(xué)習(xí)使用API和相關(guān)工具，需要在教程、案例、運(yùn)行時環(huán)境等諸多方面加強(qiáng)建設(shè)。圍繞云服務(wù)，已經(jīng)發(fā)展出許多上層生態(tài)工具，例如terraform/ansible/spinnaker等開源軟件，它們能夠幫助云服務(wù)更好地使用起來，必須對它們提供支持，如何能夠快速覆蓋也對平臺開發(fā)能力是個考驗(yàn)。

另外，API本身的質(zhì)量保障也是非常重要的。一般都要考慮性能、穩(wěn)定性、安全等方面的保障體系，通過壓測、監(jiān)控、部署防護(hù)軟件等方式來確保API在服務(wù)的時候不會掉鏈子。傳統(tǒng)的套路在解決系統(tǒng)問題時非常有效，但具體到業(yè)務(wù)問題的時候就無能為力了。例如，一個創(chuàng)建服務(wù)器的API一般來說都是要求冪等的，怎么檢測該API實(shí)際上有沒有做到冪等呢?推而廣之，其他業(yè)務(wù)流程的正確性又如何保障呢?等API開放了發(fā)現(xiàn)問題再修復(fù)就為時已晚，顯然應(yīng)該在上線前通過測試來發(fā)現(xiàn)這類問題。但是隨著業(yè)務(wù)的發(fā)展，如何能保障這類問題可以有統(tǒng)一的解決方案，能夠長期跟進(jìn)及時發(fā)現(xiàn)風(fēng)險避免損失呢?

阿里云API體系簡易圖

所謂量變引起質(zhì)變，上述問題針對單個API的時候都好解決，但是當(dāng)API規(guī)模達(dá)到成千上萬的時候，就必須通過平臺化、系統(tǒng)化的手段來解決了。例如，API服務(wù)可靠性SLA指標(biāo)如果要達(dá)到4個9，需要制定明確的標(biāo)準(zhǔn)，并且有手段監(jiān)控到所有API的運(yùn)行結(jié)果，通過分析成功率來判斷其是否達(dá)到預(yù)期水平，這對云服務(wù)本身的底層系統(tǒng)建設(shè)提出了較高的要求。

所以，以API為中心完善相關(guān)體系，保障用戶體驗(yàn)的一致性、及時性、穩(wěn)定性、易用性是非常有挑戰(zhàn)的。

https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages

https://tools.ietf.org/html/rfc7231#section-4

https://www.cnblogs.com/sparkdev/p/10052310.html

https://www.grpc.io/docs/guides/

https://www.terraform.io/docs/index.html

http://www.grabsun.com/article/2015/1135807.html