免費AI編程助手
從涂鴉到發(fā)布 —— 理解API的設(shè)計過程
要想設(shè)計出可以正常運行的Web API，對基于web的應(yīng)用的基本理解是一個良好的基礎(chǔ)。但如果你的目標(biāo)是創(chuàng)建出優(yōu)秀的API，那么僅憑這一點還遠(yuǎn)遠(yuǎn)不夠。設(shè)計優(yōu)秀的API是一個艱難的過程，如果它恰巧是你當(dāng)前的工作任務(wù)，那么你很可能會感到手足無措。
不過，優(yōu)秀的設(shè)計絕對是可以實現(xiàn)的。本文所描述的流程將幫助你獲得成功，我們將共同研究什么是優(yōu)秀的設(shè)計，以及迭代式的流程如何幫助我們實現(xiàn)這一目標(biāo)。我們還將敘述設(shè)計的三個重要階段：草圖設(shè)計、原型設(shè)計以及實現(xiàn)，同時還將介紹一些能夠讓你的工作變得更輕松的工具。
優(yōu)秀的API設(shè)計來自于迭代過程
在開始設(shè)計API之前，我們必須理解它的目的。在你手動設(shè)計之前，你應(yīng)當(dāng)了解為什么要設(shè)計這個API，如果在這方面需要幫助，有許多現(xiàn)成的資料可以參考。不過，定義你的動機(jī)僅僅是第一步，真正的訣竅在于直到實現(xiàn)為止，始終保持進(jìn)行正確的設(shè)計決策。
成功的API設(shè)計意味著要設(shè)計出一種接口，讓它的使用方式符合它的目的。作為API設(shè)計者來說，我們所做的每個決策都會影響到產(chǎn)品的成敗。設(shè)計過程中需要做出一些重大的決策，例如API所使用的傳輸協(xié)議、或它所支持的消息格式。但除此之外，還有許多相關(guān)的次要決定，例如接口的控制、名稱、關(guān)聯(lián)以及次序。而當(dāng)你將所有的決策集中在一起時，它們將帶動API的使用模式。如果你能夠做到每個決定都是正確的，那么這種模式將對API產(chǎn)生完美的支持與促進(jìn)作用。
如果你要做出一個正確的設(shè)計決策，很可能會先做出一個錯誤的決策，并從中吸取經(jīng)驗教訓(xùn)。實際上，你很可能會在多次犯錯之后才能夠接近正確的決策。這也正是迭代的關(guān)鍵所在，因為沒有人能夠做到一次成功，但只要有足夠的機(jī)會，你就能夠做到接近完美。
通過迭代方式進(jìn)行API設(shè)計，這一點說起來容易，但在實際應(yīng)用中做到這一點并不簡單。我們所面臨的一個常見的挑戰(zhàn)在于，在某個API發(fā)布之后再進(jìn)行變更是非常困難的。事實上，對一個使用中的API進(jìn)行變更的代價很大，并且伴隨著很大的風(fēng)險?；蛘呓栌肑oshua Bloch的說法：“公開的API就像鉆石，它是永恒不變的。”
處理這一問題的一種方式是在每次變更時不要破壞現(xiàn)有的接口，這是一種好習(xí)慣，也是優(yōu)秀API設(shè)計的一個主要原則。但有些時候，破壞性的變更是不可避免的，而基本層面的設(shè)計變更尤其具有侵略性。
換種思路，我們應(yīng)當(dāng)在接口發(fā)布之前就做好這些變更。在理想的情況下，在變更的代價變得高昂之前，就應(yīng)該消除易用性與設(shè)計方面的問題。當(dāng)時，只有在首次發(fā)布之前做到盡早開始迭代，并保持頻繁的迭代，才能夠找到并修復(fù)這些問題。
迭代式的設(shè)計過程
在每一次迭代中，我們都得到了一次對設(shè)計候選按其使用情況進(jìn)行評估的機(jī)會。舉例來說，開發(fā)者是否能夠通過使用我們創(chuàng)建的產(chǎn)品實現(xiàn)他的工作目標(biāo)？這個接口真的能夠?qū)崿F(xiàn)嗎？如果我們要求他人使用這個API，他們又會有什么樣的感受？
通過設(shè)計與實現(xiàn)多個接口而不發(fā)布它們，應(yīng)該能夠?qū)崿F(xiàn)最佳的API設(shè)計。通過對每個接口進(jìn)行審查與測試，我們將對于如何改進(jìn)最終產(chǎn)品具有良好的洞察力。
但是在實踐中，這種壯觀的迭代式設(shè)計是不可能實現(xiàn)的。沒有幾個人能有足夠的時間、金錢或耐心去不斷地設(shè)計與實現(xiàn)一個個可以運行的API。對于任何具有一定復(fù)雜度的接口來說，這種方式的迭代式設(shè)計會占用你過多的時間。
一個更合理的方式是在設(shè)計過程的早期就進(jìn)行迭代，這些早期的設(shè)計應(yīng)當(dāng)具有足夠的細(xì)節(jié)，可展現(xiàn)改進(jìn)的最佳時機(jī)，但又無需過度設(shè)計而導(dǎo)致實現(xiàn)的困難。隨著時間的推移，我們可以逐步地增加細(xì)節(jié)度（或保真度），并最終得到一個完整的實現(xiàn)。
這種逐步推進(jìn)的設(shè)計過程在設(shè)計界已經(jīng)非常流行了，它通常被分解為三個重要的階段：
- 草圖設(shè)計
- 原型設(shè)計
- 實現(xiàn)
草圖設(shè)計的強(qiáng)大作用
草圖設(shè)計是設(shè)計方面的一種普遍行為。著名建筑師Frank Gehry的草圖可謂天下聞名，以至于誕生了一部專門描述這些草圖的電影。他的許多建筑項目都是從在一疊紙上所畫的一系列草圖開始的。Gehry總會畫上幾百張這樣的草圖，每一次都向良好的設(shè)計更靠近一步。
交互設(shè)計師Bill Verplank將草圖設(shè)計描述為設(shè)計過程中必不可少的第一步。Bill Buxton還專門寫了一整本書，用以介紹草圖設(shè)計方法對用戶體驗設(shè)計的價值，并認(rèn)為它的關(guān)鍵特征在于它的可棄性、而且在所有探索方式中是成本最低的一種。
將草圖設(shè)計過程包含在API設(shè)計過程的早期階段，讓我們有機(jī)會體驗接口的概念模型。這不僅是一次定義我們腦中已有的想法的好機(jī)會，也讓我們有機(jī)會探索新的道路，并且提出“如果……會怎么樣？”這樣的問題，并逐步走向真正的創(chuàng)新。
優(yōu)秀的草圖應(yīng)當(dāng)是易于創(chuàng)建、并且可以任意丟棄的。如果創(chuàng)建這些草圖花費了許多時間、或是難度太高，那么你就難以丟棄它們。這種可棄性非常重要，它讓我們有機(jī)會承受住風(fēng)險。
我們可以通過草圖設(shè)計嘗試不同類型的接口風(fēng)格，并捉住那些在我們腦海中時而閃現(xiàn)的抽象概念。一旦這些思想具體化，我們就能夠?qū)λ鼈冞M(jìn)行審查及討論。在過程中決定我們喜歡或是不喜歡某個特定的概念，然后在消化了這些知識后再次啟動這一過程，并繪制新的草圖。
對于設(shè)計團(tuán)隊之外的用戶來說，他們很少會對草圖進(jìn)行評估。不僅是因為過早地對假設(shè)進(jìn)行驗證是沒有價值的，并且在實際的項目中能夠進(jìn)行的用戶測試次數(shù)是有限的。通過真實的用戶對每種草圖都進(jìn)行測試的設(shè)想代價過高，而這種方式的收獲是非常有限的。
使用檔案進(jìn)行草圖設(shè)計
在進(jìn)行API的草圖設(shè)計時，使用檔案（profile）或元語言（meta language）是一種非常實用的方式。檔案提供了一系列的概念，可用于草圖的設(shè)計。一個優(yōu)秀的檔案可以類比為框與線，通過它創(chuàng)建系統(tǒng)圖的多種草圖。這些元素是設(shè)計師與評估者都能夠理解的內(nèi)容，它讓快速地開發(fā)草圖變得更簡單。
實際上，著手進(jìn)行API草圖設(shè)計過程有一種好方法，就是定義接口中最明顯的單詞列表。有哪些單詞是用戶必須知道的？哪些單詞能夠最好地表達(dá)你的目標(biāo)受眾的目的與任務(wù)？通過回答這些問題，并創(chuàng)建一份接口的詞匯表，將有助于你形成對該接口的一種早期草圖。
檔案的美妙之處在于，它為我們提供了一種正規(guī)化的方式以共享及重用這種類型的信息。舉例來說，我們在開始設(shè)計時可能會從某個XML結(jié)構(gòu)文檔中提取出單詞、從schema.org獲取一份詞匯表、或者從某個ALPS或RDF文檔獲取信息，這取決于我們的需求。
設(shè)計階段的目標(biāo)并非創(chuàng)建一份全面的詞匯表，恰恰相反，早期的詞匯表只是一個起點，我們可以從這一點開始繪制出其它類型的細(xì)節(jié)。我們可能會發(fā)現(xiàn)一個由20個左右的單詞組成的列表就能夠捕獲接口的本質(zhì)，這個列表就可以作為我們的起點。
這份詞匯表為我們提供了一個基礎(chǔ)，我們可以從它出發(fā)為API中的資源與關(guān)聯(lián)設(shè)計草圖，內(nèi)容可以包括URI、資源名稱、資源間的關(guān)聯(lián)、鏈接文本以及其它結(jié)構(gòu)化以及導(dǎo)航元素。請再次注意，沒有必要畫出草圖的所有細(xì)節(jié)，我們的目標(biāo)是表達(dá)出API里最重要的部分。
最重要的一點在于，最初的草圖無需過于深入。比方說，請盡量避免在這一階段就深入到錯誤流的建模，或響應(yīng)消息元素的設(shè)計。這些部分可以稍后再加入，或者可以為它們進(jìn)行專門的草圖設(shè)計。
一份單獨的草圖無需反映出整個接口，實際上，為某些細(xì)節(jié)部分專門設(shè)計草圖的方式可能更實用。舉例來說，我們可以設(shè)計一個基本錯誤流的草圖，它與整個API都具有相關(guān)性，或是設(shè)計一種響應(yīng)消息格式的草圖，這種格式可以應(yīng)用到所有響應(yīng)中。之后，在原型設(shè)計階段，我們可以將這些思想應(yīng)用到某個工作模型中。
原型設(shè)計
在原型設(shè)計階段，我們將有機(jī)會為接口設(shè)計一個具有更高保真度的模型，并且對草圖設(shè)計階段產(chǎn)生的一些假設(shè)進(jìn)行驗證。一個優(yōu)秀的API原型應(yīng)當(dāng)是可以調(diào)用的，它應(yīng)當(dāng)能夠處理真實的請求消息，并在必要時提供響應(yīng)。開發(fā)者甚至應(yīng)該能夠通過使用這個原型API，創(chuàng)建出一個簡單的應(yīng)用。
不過，創(chuàng)建原型的成本應(yīng)當(dāng)?shù)陀谝粋€完整的實現(xiàn)。有一種方法可以保持較低的成本，即模擬響應(yīng)的消息，而不是由后臺系統(tǒng)輸出真實的響應(yīng)消息。這種方式有時也稱為接口的虛構(gòu)（mocking），它是一種建立快速原型的好方法。
無論使用哪種方法建立原型，要點在于為投入找到一個合適的范圍，能夠支持后續(xù)的迭代。我們應(yīng)當(dāng)能夠基于草圖創(chuàng)建出兩至三個不同的原形，并在過程中持續(xù)地學(xué)習(xí)。根據(jù)我們在原型設(shè)計階段所學(xué)的內(nèi)容，我們甚至可能會返回草圖設(shè)計階段，并嘗試全新的方向。
通過原型，你的團(tuán)隊將有機(jī)會獲得對于設(shè)計的早期用戶反饋，并且能夠?qū)φ鎸嵉氖褂们闆r進(jìn)行觀察。如果該接口的保真度已經(jīng)達(dá)到了一定程度，你就可以讓潛在的用戶創(chuàng)建應(yīng)用，并且對他們在實現(xiàn)階段所面臨的挑戰(zhàn)進(jìn)行觀察。
負(fù)責(zé)實現(xiàn)的成員也應(yīng)當(dāng)加入原形評估過程中。一個經(jīng)過良好設(shè)計的API不僅應(yīng)當(dāng)易于使用，同時還是可持續(xù)的、可靠的、高性能的、并且是歷時長久的。雖然接口本身不應(yīng)暴露數(shù)據(jù)模型的內(nèi)部細(xì)節(jié)與服務(wù)器的架構(gòu)，但負(fù)責(zé)實現(xiàn)者為告訴設(shè)計團(tuán)隊所做的決定提供一些參考建議，例如運行環(huán)境的限制，以及實現(xiàn)的成本。
設(shè)計周期好比一個科學(xué)工藝流程，而你應(yīng)當(dāng)抓住原型階段的這次機(jī)會，在提出變更還為時未晚時對所做的假設(shè)進(jìn)行驗證。
實現(xiàn)
實現(xiàn)者的任務(wù)是將一個原型化的接口轉(zhuǎn)變成一種可以放心地進(jìn)行實際應(yīng)用的產(chǎn)品。交付一個安全的、可靠的、以及可伸縮的實現(xiàn)是一個很大的挑戰(zhàn)，這一過程本身也需要經(jīng)歷一種專門的設(shè)計流程。
最后的原型以及支持性的草圖描述了接口應(yīng)該表現(xiàn)出的樣子，它們反映出了所有的設(shè)計決策，并形成了一份規(guī)格，說明了具體需要創(chuàng)建什么樣的產(chǎn)品。實際上，可以使用一種正式的接口描述語言（或稱IDL），從原型階段自然地過渡到實現(xiàn)階段。
舉例來說，如果你對原型API感到滿意，就可以選擇以一種API Blueprint文檔（或Swagger、RAML、WADL，又或者是其它任何一種最適合你工作環(huán)境的格式）對其進(jìn)行描述。
雖然這一階段的目標(biāo)是實現(xiàn)，但也不應(yīng)停下設(shè)計的腳步。這一階段是一個良機(jī)，讓你通過真實的使用數(shù)據(jù)對整個設(shè)計過程中所做的假設(shè)進(jìn)行進(jìn)一步的驗證。就像原型化的API允許我們觀察使用情況一樣，實現(xiàn)后的API允許我們在一個宏觀層面對使用情況進(jìn)行分析。
打個比方，你或許想對你之前所做的設(shè)計假設(shè)進(jìn)行驗證。應(yīng)用程序的開發(fā)者是否真的在使用你為他們所創(chuàng)建的便利的操作？你是否吸引到你所期望的用戶類型？新的用戶是否在使用接口中的某些部分時遇到了麻煩？
經(jīng)過分析，你可能會重新開始一次草圖設(shè)計過程，以準(zhǔn)備經(jīng)過進(jìn)一步改進(jìn)的接口。
通過工具實現(xiàn)過程的自動化
工具與技術(shù)的使用會極大地改進(jìn)整個設(shè)計過程。那些能夠降低草圖與原型創(chuàng)建成本的工具能夠讓設(shè)計團(tuán)隊在更短的時間內(nèi)創(chuàng)建更多的細(xì)節(jié)，使設(shè)計的決策得到改進(jìn)。
對于多數(shù)設(shè)計過程來說，工具與自動化的引入是一個重要的部分。在建筑設(shè)計的世界中，SHoP（一個位于紐約的建筑師事務(wù)所）就通過創(chuàng)新、合作與基于工具的設(shè)計獲得了成功。他們的流程中就引入了原型工具，讓設(shè)計師能夠體現(xiàn)出所用材料的物理特性。這種方法讓他們得以創(chuàng)建數(shù)以千計的設(shè)計迭代，在每次迭代中都能夠體現(xiàn)出易于評估的實現(xiàn)細(xì)節(jié)。
在API設(shè)計的世界中，這種基于工具的優(yōu)化有很好的表現(xiàn)機(jī)會。實際上，在服務(wù)描述領(lǐng)域中，已經(jīng)出現(xiàn)了一些卓越的Web API設(shè)計工具。
接口描述語言也能夠提供支持性的工具，以簡化編寫描述的任務(wù)，這一點現(xiàn)在已經(jīng)很常見了。這些編輯器工具能夠縮短基于IDL的設(shè)計的創(chuàng)建時間，因此在更短的時間內(nèi)創(chuàng)建更多的描述也變得更容易了。Swagger、RAML與Blueprint都提供了優(yōu)秀的編輯工具以支持各自的語言。即使像WADL這樣僅作為規(guī)范發(fā)布的IDL，也能夠從SoapUI這樣的工具中受益。
Apiary為Blueprint語言所提供的編輯器有很強(qiáng)的競爭力，因為它提供了一套完整的工作流工具以支持設(shè)計過程。只要以Blueprint編寫一個簡單的API描述，設(shè)計師就能夠?qū)ξ臋n進(jìn)行評估、調(diào)用原型，甚至對調(diào)用過程進(jìn)行分析。
(**單擊圖片以放大**)
不過，這些現(xiàn)有的工具中的大部分都只限于其所支持的描述語言。設(shè)計者必須理解IDL的語法，并且用這種語言設(shè)計界面。雖然這種設(shè)計風(fēng)格能夠吸引熟悉編程語言的使用者，但也會限制在早期的草圖設(shè)計階段很有價值的抽象與實驗性的思考方式。
由于IDL及其對應(yīng)工具的這些特征，它們很適用于原型設(shè)計過程，但對于草圖設(shè)計的早期實驗性活動來說實用性不高。
使用可視化工具進(jìn)行草圖設(shè)計
人們對于使用可視化工具幫助他們進(jìn)行API設(shè)計的興趣正在不斷升溫。這些工具并非直接支持編輯IDL的行為，而是讓設(shè)計者能夠隨意擺弄接口的一個可視化展現(xiàn)。
可視的建模工具提供了一種接口描述語言，這種語言多數(shù)是關(guān)于繪畫的，或是基于圖形的。雖然這個視角限制了接口展現(xiàn)的準(zhǔn)確度，但它也讓設(shè)計者能夠在一個較高層次看到這個接口的全貌。這一點帶來了進(jìn)行改進(jìn)的機(jī)會，而這種機(jī)會在手寫的形式中往往并不明顯。
易于使用的可視化編輯器也是進(jìn)行自動化草圖設(shè)計的良好選擇，它綜合了低保真度、抽象的展現(xiàn)以及可棄性等特征，這正是我們所需的。
我參與開發(fā)了一個名為Rápido!的可視化建模工具，用于輔助API的草圖設(shè)計。Rápido將用戶限制在一個低保真度的細(xì)節(jié)中，這一點并非它的副作用，而是本身就是如此設(shè)計的。用戶可以使用它進(jìn)行檔案、導(dǎo)航元素以及響應(yīng)數(shù)據(jù)的建模，但不能用于設(shè)計邏輯流程或動態(tài)的響應(yīng)。
當(dāng)設(shè)計者開始創(chuàng)建一個新的Rápido項目時，他們需要為API設(shè)計一個詞匯表。在得到一個初始的單詞列表（或者從外部導(dǎo)入一個ALPS詞匯表）之后，設(shè)計師就可以在一個超媒體畫布中開始為API設(shè)計概念模型、創(chuàng)建資源、嘗試URI名稱甚至是鏈接的狀態(tài)。
最終，設(shè)計者可以為草圖中的每個資源或狀態(tài)實現(xiàn)靜態(tài)的響應(yīng)消息，以增加保真度。最后，當(dāng)草圖設(shè)計階段結(jié)束后，可以將整個設(shè)計導(dǎo)出成IDL格式，準(zhǔn)備在原型階段導(dǎo)入高保真度的工具。
Rápido的目標(biāo)是在Web API設(shè)計的領(lǐng)域中提供一種快速繪制的“雞尾酒餐巾”式的草圖的體驗。如果你選擇了適當(dāng)?shù)谋Ｕ娑?，并且沒有施加過于強(qiáng)烈的限制，那么它就能夠成為API設(shè)計工具鏈中的重要一環(huán)。
在迭代過程中取得成功
如果你按照本文中所描述的方式進(jìn)行迭代式風(fēng)格的設(shè)計，那么你將為團(tuán)隊帶來一個設(shè)計高效API的良機(jī)。在過程的一開始創(chuàng)建多個低保真度的設(shè)計并進(jìn)行評估，以培育實驗?zāi)芰εc構(gòu)思能力。然后創(chuàng)建高保真度的原型以及虛擬的實現(xiàn)，以評估早期的設(shè)計思想。最后，為真實用戶實現(xiàn)整個設(shè)計，并獲取數(shù)據(jù)以分析實際應(yīng)用中的使用情況。
迭代式設(shè)計過程的特定細(xì)節(jié)取決于你的環(huán)境與項目，需要多少細(xì)節(jié)、多少次迭代、以及需要哪些評估技術(shù)，這些問題將留給設(shè)計者進(jìn)行回答。但作為一種通用的經(jīng)驗法則，隨著你的設(shè)計過程的推移，迭代的數(shù)量應(yīng)當(dāng)逐步減少，而在評估方面需要投入更多的精力。
優(yōu)秀的API設(shè)計過程為你提供了一個創(chuàng)建最佳的接口的機(jī)會。但創(chuàng)建優(yōu)秀API的秘密并不在于專家的指導(dǎo)或什么神秘的知識，而是一種通過優(yōu)秀的工具、語言以及檔案所優(yōu)化的迭代流程的應(yīng)用而實現(xiàn)的。使用這個公式所交付的API定能幫助你的組織獲得成功。
關(guān)于作者
Ronnie Mitra是CA Technologies公司的API Academy部門的API設(shè)計總監(jiān)。他多次幫助遍布全球的組織成功地完成了API的設(shè)計與實現(xiàn)。Ronnie具有超過30年的行業(yè)經(jīng)驗，在此期間內(nèi)他不斷地在失敗中進(jìn)行學(xué)習(xí)。
更多建議：