Web API設(shè)計(jì)方法論

1、Web API設(shè)計(jì)方法論為Web設(shè)計(jì)、實(shí)現(xiàn)和維護(hù)API不僅僅是一項(xiàng)挑戰(zhàn)；對很多公司來說，這是一項(xiàng)勢在必行的任務(wù)。本系列 將帶領(lǐng)讀者走過一段旅程，從為API確定業(yè)務(wù)用例到設(shè)計(jì)方法論，解決實(shí)現(xiàn)難題，并從長遠(yuǎn)的角度看待在Web上維護(hù)公共API。沿途將會(huì)有對有影響力的人物的訪談，甚至還有API及相關(guān)主題的推薦閱讀清單。這篇 InfoQ文章是 Web API從開始到結(jié)束系列文章中的一篇。你可以在這里進(jìn)行訂閱，以便能在有新文章發(fā)布時(shí)收到通知。設(shè)計(jì)Web API不止是URL、HTTP狀態(tài)碼、頭信息和有效負(fù)載。設(shè)計(jì)的過程-基本上是為了你的API“觀察和感受” - 這非常重要，并且

2、值得你付出努力。本文簡要概括了一種同時(shí)發(fā)揮HTTP和Web兩者優(yōu)勢的API設(shè)計(jì)方法論。并且它不僅對HTTP有效。如果有時(shí)你還需要通過WebSockets、XMPP、MQTT等實(shí)現(xiàn)同樣的服務(wù)，大部分API設(shè)計(jì)的結(jié)果同樣可用?？梢宰屛磥碇С侄喾N協(xié)議更容易實(shí)現(xiàn)和維護(hù)。優(yōu)秀的設(shè)計(jì)超越了URL、狀態(tài)碼、頭信息和有效負(fù)載一般來說， Web API設(shè)計(jì)指南的重點(diǎn)是通用的功能特性，比如URL設(shè)計(jì)，正確使用狀態(tài)碼、方法、頭信息之類的HTTP功能特性，以及持有序列化的對象或?qū)ο髨D的有效負(fù)載設(shè)計(jì)。這些都是重要的實(shí)現(xiàn)細(xì)節(jié)，但不太算得上API設(shè)計(jì)。并且正是API的設(shè)計(jì)-服務(wù)的基本功能特性的表達(dá)和描述方式-為Web AP

3、I的成功和可用性做出了重要貢獻(xiàn)。一個(gè)優(yōu)秀的設(shè)計(jì)過程或方法論定義了一組一致的、可重復(fù)的步驟集，可以在將一個(gè)服務(wù)器端服務(wù)組件輸出為一個(gè)可訪問的、有用的Web API時(shí)使用。那就是說，一個(gè)清晰的方法論可以由開發(fā)人員、設(shè)計(jì)師和軟件架構(gòu)師共享，以便在整個(gè)實(shí)現(xiàn)周期內(nèi)幫助大家協(xié)同活動(dòng)。一個(gè)成熟的方法論還可以隨著時(shí)間的發(fā)展，隨著每個(gè)團(tuán)隊(duì)不斷發(fā)現(xiàn)改善和精簡過程的方式而得到精煉，卻不會(huì)對實(shí)現(xiàn)細(xì)節(jié)產(chǎn)生不利的影響。實(shí)際上，當(dāng)實(shí)現(xiàn)細(xì)節(jié)和設(shè)計(jì)過程兩者都有清晰的定義并相互分離時(shí)，實(shí)現(xiàn)細(xì)節(jié)的改變（比如采用哪個(gè)平臺(tái)、OS、框架和UI樣式）可以獨(dú)立于設(shè)計(jì)過程。API設(shè)計(jì)七步法接下來我們要對Richardson和Amundsen合

4、著的REST風(fēng)格的Web API一書中所介紹的設(shè)計(jì)方法論做簡要地概述。因?yàn)槠?，我們不能深入探討這一過程中的每一步驟，但這篇文章可以讓你有個(gè)大概的認(rèn)識(shí)。另外，讀者可以用這篇概述作為指南，根據(jù)自己組織的技能和目標(biāo)開發(fā)一個(gè)獨(dú)有的Web API設(shè)計(jì)過程。說明：是的，7步看起來有點(diǎn)兒多。實(shí)際上清單中有5個(gè)步驟屬于設(shè)計(jì)，額外還有兩個(gè)條目是實(shí)現(xiàn)和發(fā)布。最后這兩個(gè)設(shè)計(jì)過程之外的步驟是為了提供一個(gè)從頭到尾的體驗(yàn)。你應(yīng)該計(jì)劃好根據(jù)需要重新迭代這些步驟。通過步驟2（繪制狀態(tài)圖）意識(shí)到在步驟1（列出所有組成部分）有更多工作要做。當(dāng)你接近于寫代碼（步驟6）時(shí)，可能會(huì)發(fā)現(xiàn)第5步（創(chuàng)建語義檔案）中漏了一些東西。關(guān)鍵是

5、用這個(gè)過程暴露盡可能多的細(xì)節(jié)，并愿意回退一步或者兩步，把前面漏掉的補(bǔ)上。迭代是構(gòu)建更加完整的服務(wù)畫面以及澄清如何將它暴露給客戶端程序的關(guān)鍵。步驟1 : 列出所有組成部分第一步是列出客戶端程序可能要從我們的服務(wù)中獲取的，或要放到我們的服務(wù)中的所有數(shù)據(jù)片段。我們將這些稱為語義描述符。語義是指它們處理數(shù)據(jù)在應(yīng)用程序中的含義，描述符是指它們描述了在應(yīng)用程序自身中發(fā)生了什么。注意，這里的視點(diǎn)是客戶端，不是服務(wù)器端。將API設(shè)計(jì)成客戶端使用的東西很重要。比如說，在一個(gè)簡單的待辦事項(xiàng)列表應(yīng)用中，你可能會(huì)找到下面這些語義描述符：· id : 系統(tǒng)中每條記錄的唯一標(biāo)識(shí)符· title : 每

6、個(gè)待辦事項(xiàng)的標(biāo)題· dateDue : 待辦事項(xiàng)應(yīng)該完成的日期· complete : 一個(gè)是/否標(biāo)記，表明待辦事項(xiàng)是否已經(jīng)完成了。在一個(gè)功能完備的應(yīng)用程序中，可能還會(huì)有很多語義描述符，涉及待辦事項(xiàng)的分類（工作、家庭、園藝等），用戶信息（用于多用戶的實(shí)現(xiàn)）等等。不過為了突出過程本身，我們會(huì)保持它的簡單性。步驟2 : 繪制狀態(tài)圖下一步是根據(jù)建議的API繪制出狀態(tài)圖。圖中的每個(gè)框都表示一種可能的表示-一個(gè)包含在步驟1中確定的一或多個(gè)語義描述符的文檔。你可以用箭頭表示從一個(gè)框到下一個(gè)的轉(zhuǎn)變-從一個(gè)狀態(tài)到下一個(gè)狀態(tài)。這些轉(zhuǎn)變是由協(xié)議請求觸發(fā)的。在每次變化中還不用急著指明用哪個(gè)協(xié)議方

7、法。只要標(biāo)明變化是安全的（比如HTTP GET），還是不安全/非冪等的（比如HTTP.POST），或者不安全/冪等的（PUT）。說明：冪等動(dòng)作是指重復(fù)執(zhí)行時(shí)不會(huì)有無法預(yù)料的副作用。比如HTTP PUT ，因?yàn)橐?guī)范說服務(wù)器應(yīng)該用客戶端傳來的狀態(tài)值替換目標(biāo)資源的已有值，所以說它是冪等的。而 HTTP POST 是非冪等的，因?yàn)橐?guī)范指出提交的值應(yīng)該是追加到已有資源集合上的，而不是替換。在這個(gè)案例中，我們這個(gè)簡單的待辦事項(xiàng)服務(wù)的客戶端應(yīng)用程序可能需要訪問可用條目的清單，能過濾這個(gè)清單，能查看單個(gè)條目，并且能將條目標(biāo)記為已完成。這些動(dòng)作中很多都用狀態(tài)值在

8、客戶端和服務(wù)器之間傳遞數(shù)據(jù)。比如add-item 動(dòng)作允許客戶端傳遞狀態(tài)值title和dueDate。下面是一個(gè)說明那些動(dòng)作的狀態(tài)圖。這個(gè)狀態(tài)圖中展示的這些動(dòng)作（也在下面列出來了）也是語義描述符- 它們描述了這個(gè)服務(wù)的語義動(dòng)作。· read-list· filter-list· read-item· create-item· mark-complete在你做這個(gè)狀態(tài)圖的過程中，你可能會(huì)發(fā)現(xiàn)自己漏掉了客戶端真正想要或需要的動(dòng)作或數(shù)據(jù)項(xiàng)。這是退回到步驟1的機(jī)會(huì)，添加一些新的描述符，并/或者在步驟2中改進(jìn)狀態(tài)圖。在你重新迭代過這兩步之后，你應(yīng)該對客戶

9、端跟服務(wù)交互所需的所有數(shù)據(jù)點(diǎn)和動(dòng)作有了好的認(rèn)識(shí)和想法。步驟 3 : 調(diào)和魔法字符串下一步是調(diào)和服務(wù)接口中的所有“魔法字符串”?！澳Хㄗ址?全是描述符的名稱-它們沒有內(nèi)在的含義，只是表示客戶端跟你的服務(wù)通訊時(shí)將要訪問的動(dòng)作或數(shù)據(jù)元素。調(diào)和這些描述符名稱的意思是指采用源自下面這些地方的，知名度更高的公共名稱：· S· · Dublin Core· IANA Link Relation Values這些全是明確定義的、共享的名稱庫。當(dāng)你服務(wù)接口使用來自這些源頭的名稱時(shí)，開發(fā)人員很可能之前見過并知道它們是什么

10、意思。這可以提高API的可用性。說明：盡管在服務(wù)接口上使用共享名稱是個(gè)好主意，但在內(nèi)部實(shí)現(xiàn)里可以不用（比如數(shù)據(jù)庫里的數(shù)據(jù)域名稱）。服務(wù)自身可以毫不困難地將公共接口名稱映射為內(nèi)部存儲(chǔ)名稱。以待辦事項(xiàng)服務(wù)為例，除了一個(gè)語義描述符- create-item，我能找到所有可接受的已有名稱。為此我根據(jù)Web Linking RFC5988中的規(guī)則創(chuàng)建了一個(gè)具有唯一性的URI。在給接口描述符選擇知名的名稱時(shí)需要折中。它們極少能跟你的內(nèi)部數(shù)據(jù)存儲(chǔ)元素完美匹配，不過那沒關(guān)系。這里是我的結(jié)果：· id -> 來自Dublin Core的identifier· title -&

11、#160;來自S的name· dueDate -> 來自S的scheduledTime· complete -> 來自S的status· read-list -> 來自IANA Link Relation Values的collection· filter-list -> 來自IANA Link Relation Values的search· read-item -> 來自IANA Link Relation V

12、alues的item· create-item ->用RFC5988的· mark-complete - 來自IANA Link Relation Values的edit經(jīng)過名稱調(diào)和，我的狀態(tài)圖變成了下面這樣：步驟 4 : 選一個(gè)媒體類型API設(shè)計(jì)過程的下一步是選一個(gè)媒體類型，用來在客戶端和服務(wù)器端之間傳遞消息。Web的特點(diǎn)之一是數(shù)據(jù)是通過統(tǒng)一的接口作為標(biāo)準(zhǔn)化文檔傳輸?shù)?。選擇同時(shí)支持?jǐn)?shù)據(jù)描述符（比如"identifier"、"status"等）和動(dòng)作描述符（比如"search"、"edit

13、"等）的媒體類型很重要。有相當(dāng)多可用的格式。在我寫這篇文章時(shí)，一些頂尖的超媒體格式是 (排名不分先后)：· 超文本標(biāo)記語言 (HTML)· 超文本應(yīng)用程序語言(HAL)· Collection+JSON (Cj)· Siren· JSON-API· 交換表達(dá)式的統(tǒng)一基礎(chǔ) (UBER)讓所選擇的媒體類型適用于你的目標(biāo)協(xié)議也很重要。大多數(shù)開發(fā)人員喜歡用HTTP 協(xié)議做服務(wù)接口。然而WebSockets、XMPP、MQTT和CoAP 也會(huì)用-特別是對于高速、短消息、端到端的實(shí)現(xiàn)。在這個(gè)例子中，我會(huì)以HTML為消

14、息格式，并采用HTTP協(xié)議。HTML有所有數(shù)據(jù)描述符所需的支持(<UL>用于列表， <LI>用于條目， <SPAN>用于數(shù)據(jù)元素)。它也有足夠的動(dòng)作描述符支持 (<A>用于安全鏈接， <FORM method="get">用于安全轉(zhuǎn)變， <FORM method="post">用于非安全轉(zhuǎn)變）。注意：在這個(gè)狀態(tài)圖中， “編輯”動(dòng)作是冪等的（比如HTTP PUT），并且HTML仍然沒有對PUT的原生支持。在這個(gè)例子中，我會(huì)添加一個(gè)域來將HTML的POST做成冪等的。好了，現(xiàn)在

15、我可以基于那個(gè)狀態(tài)圖創(chuàng)建一些樣例表示來“試試”這個(gè)接口了。對我們的例子而言，只有兩個(gè)表示要渲染：“待辦事項(xiàng)列表”和“待辦事項(xiàng)條目”表示：圖1 ：用HTML表示待辦事項(xiàng)列表集合圖2 ：用HTML表示待辦事項(xiàng)條目記住，在你做狀態(tài)圖的表示樣例時(shí)，可能會(huì)發(fā)現(xiàn)之前的步驟中有所遺漏（比如漏掉描述符，動(dòng)作描述符中有冪等之類的變化等）。那也沒關(guān)系?，F(xiàn)在就是解決所有這些問題的時(shí)機(jī)- 在你把這個(gè)設(shè)計(jì)變成代碼之前。等你對表示完全滿意之后，在開始寫代碼之前還有一個(gè)步驟-創(chuàng)建語義檔案。步驟 5 : 創(chuàng)建語義檔案語義檔案是一個(gè)文檔，其中列出了設(shè)計(jì)中的所有描述符，包括對開發(fā)人員構(gòu)建客戶端和服務(wù)器端實(shí)現(xiàn)有

16、幫助的所有細(xì)節(jié)。這個(gè)檔案是一個(gè)實(shí)現(xiàn)指南，不是實(shí)現(xiàn)描述。這個(gè)差別很重要。服務(wù)描述符的格式服務(wù)描述文檔格式已經(jīng)出現(xiàn)了相當(dāng)長一段時(shí)間了，并且當(dāng)你想給已有的服務(wù)實(shí)現(xiàn)生產(chǎn)代碼或文檔時(shí)很方便。確實(shí)有很多種格式。在我寫這篇文章時(shí)，頂級(jí)競爭者有：· Web服務(wù)定義語言(WSDL)· 原子服務(wù)描述(AtomSvc)· Web應(yīng)用程序描述語言(WADL)· Blueprint· Swagger· REST風(fēng)格的應(yīng)用程序建模語言(RAML)檔案的格式現(xiàn)在只有幾種檔案格式。我們推薦下面兩種：· 應(yīng)用級(jí)語義檔案 (ALPS)· JSON-L

17、D + Hydra這兩個(gè)都比較新。JSON-LD規(guī)范在2014年早期達(dá)成了W3C推薦狀態(tài)。Hydra仍是一個(gè)非官方草案（本文寫成時(shí)還是），有一個(gè)活躍的開發(fā)者社區(qū)。ALPS仍處于IETF的早期草案階段。因?yàn)闄n案文檔的理念是要描述一個(gè)問題空間的現(xiàn)實(shí)生活方面（不只是那一空間中的單一實(shí)現(xiàn)），所以其格式跟典型的描述格式十分不同：圖3 : ALPS格式的待辦事項(xiàng)列表語義檔案你會(huì)注意到，這個(gè)文檔就像一個(gè)基本的詞匯表，包含了待辦事項(xiàng)服務(wù)接口中所有可能的數(shù)據(jù)值和動(dòng)作-就是這個(gè)理念。同意遵循這個(gè)檔案的服務(wù)可以自行決定它們的協(xié)議、消息格式甚至URL。同意接受這個(gè)檔案的客戶端將會(huì)構(gòu)建為可以識(shí)別，如

18、果合適的話，啟用這個(gè)文檔中的描述符。這種格式也很適合生成人類可讀的文檔，分析相似的檔案，追蹤哪個(gè)檔案用得最廣泛，甚至生成狀態(tài)圖。但那是另外一篇文章的課題了?，F(xiàn)在你有完整的已調(diào)和名稱的描述符清單，已標(biāo)記的狀態(tài)圖，以及一個(gè)語義檔案文檔，可以開始準(zhǔn)備編碼實(shí)現(xiàn)樣例服務(wù)器和客戶端了。步驟 6 : 寫代碼到了這一步，你應(yīng)該可以將設(shè)計(jì)文檔（狀態(tài)圖和語義檔案）交給服務(wù)器和客戶端程序的開發(fā)人員了，讓他們開始做具體的實(shí)現(xiàn)。HTTP服務(wù)器應(yīng)該實(shí)現(xiàn)在第2步中創(chuàng)建的狀態(tài)圖，并且來自客戶端的請求應(yīng)該觸發(fā)正確的狀態(tài)轉(zhuǎn)變。服務(wù)發(fā)送的每個(gè)表示都應(yīng)該用第3步中選好的格式，并且應(yīng)該包含一個(gè)第4步中創(chuàng)建的指向一個(gè)檔案的鏈接。響應(yīng)中應(yīng)該包含相應(yīng)的超媒體控件，實(shí)現(xiàn)了在狀態(tài)圖中顯示、并在檔案文檔中描述的動(dòng)作?？蛻舳撕头?wù)器端開發(fā)人員在這時(shí)可以創(chuàng)建相對獨(dú)立的實(shí)現(xiàn)，并用測試驗(yàn)證其是否遵守了狀態(tài)圖和檔案。有了穩(wěn)定的可運(yùn)行代碼，還有一步要做：發(fā)布。步驟 7 : 發(fā)布你的APIWeb API應(yīng)該至少發(fā)布一個(gè)總能給客戶端響應(yīng)的URL - 即便是在遙遠(yuǎn)的將來。我將其稱為“看板URL” -每個(gè)人都知道的。發(fā)布檔案文檔也是個(gè)好主意，服務(wù)的新實(shí)現(xiàn)可以在響應(yīng)中鏈接它。你還可以發(fā)布人類可讀的文檔、教程等，以幫助開發(fā)人員理解和使用你的服務(wù)。做好這個(gè)之后，你應(yīng)該有了一個(gè)設(shè)計(jì)良好的、穩(wěn)定的、可訪問的服務(wù)運(yùn)行起來了