從塗鴉到發佈——理解API的設計過程（轉）

　　英文原文：From Doodles to Delivery: An API Design Process

　　要想設計出能夠正常運行的Web API，對基於web的應用的基本理解是一個良好的基礎。但若是你的目標是建立出優秀的API，那麼僅憑這一點還遠遠不夠。設計優秀的API是一個艱難的過程，若是它恰巧是你當前的工做任務，那麼你極可能會感到手足無措。

　　不過，優秀的設計絕對是能夠實現的。本文所描述的流程將幫助你得到成功，咱們將共同研究什麼是優秀的設計，以及迭代式的流程如何幫助咱們實現這一目標。咱們還將敘述設計的三個重要階段：草圖設計、原型設計以及實現，同時還將介紹一些可以讓你的工做變得更輕鬆的工具。

　　優秀的API設計來自於迭代過程

　　在開始設計API以前，咱們必須理解它的目的。在你手動設計以前，你應當瞭解爲何要設計這個API，若是在這方面須要幫助，有許多現成的資料能夠參考。不過，定義你的動機僅僅是第一步，真正的訣竅在於直到實現爲止，始終保持進行正確的設計決策。

　　成功的API設計意味着要設計出一種接口，讓它的使用方式符合它的目的。做爲API設計者來講，咱們所作的每一個決策都會影響到產品的成敗。設計過程當中須要作出一些重大的決策，例如API所使用的傳輸協議、或它所支持的消息格式。但除此以外，還有許多相關的次要決定，例如接口的控制、名稱、關聯以及次序。而當你將全部的決策集中在一塊兒時，它們將帶動API的使用模式。若是你可以作到每一個決定都是正確的，那麼這種模式將對API產生完美的支持與促進做用。

　　若是你要作出一個正確的設計決策，極可能會先作出一個錯誤的決策，並從中吸收經驗教訓。實際上，你極可能會在屢次犯錯以後纔可以接近正確的決策。這也正是迭代的關鍵所在，由於沒有人可以作到一次成功，但只要有足夠的機會，你就可以作到接近完美。

　　經過迭代方式進行API設計，這一點提及來容易，但在實際應用中作到這一點並不簡單。咱們所面臨的一個常見的挑戰在於，在某個API發佈以後再進行變動是很是困難的。事實上，對一個使用中的API進行變動的代價很大，而且伴隨着很大的風險。或者借用Joshua Bloch的說法：「公開的API就像鑽石，它是永恆不變的。」

　　處理這一問題的一種方式是在每次變動時不要破壞現有的接口，這是一種好習慣，也是優秀API設計的一個主要原則。但有些時候，破壞性的變動是不可避免的，而基本層面的設計變動尤爲具備侵略性。

　　換種思路，咱們應當在接口發佈以前就作好這些變動。在理想的狀況下，在變動的代價變得高昂以前，就應該消除易用性與設計方面的問題。當時，只有在首次發佈以前作到儘早開始迭代，並保持頻繁的迭代，纔可以找到並修復這些問題。

　　迭代式的設計過程

　　在每一次迭代中，咱們都獲得了一次對設計候選按其使用狀況進行評估的機會。舉例來講，開發者是否可以經過使用咱們建立的產品實現他的工做目標？這個接口真的可以實現嗎？若是咱們要求他人使用這個API，他們又會有什麼樣的感覺？

　　經過設計與實現多個接口而不發佈它們，應該可以實現最佳的API設計。經過對每一個接口進行審查與測試，咱們將對於如何改進最終產品具備良好的洞察力。

　　可是在實踐中，這種壯觀的迭代式設計是不可能實現的。沒有幾我的能有足夠的時間、金錢或耐心去不斷地設計與實現一個個能夠運行的API。對於任何具備必定複雜度的接口來講，這種方式的迭代式設計會佔用你過多的時間。

　　一個更合理的方式是在設計過程的早期就進行迭代，這些早期的設計應當具備足夠的細節，可展示改進的最佳時機，但又無需過分設計而致使實現的困難。隨着時間的推移，咱們能夠逐步地增長細節度（或保真度），並最終獲得一個完整的實現。

　　這種逐步推動的設計過程在設計界已經很是流行了，它一般被分解爲三個重要的階段：

1. 草圖設計
2. 原型設計
3. 實現

　　草圖設計的強大做用

　　草圖設計是設計方面的一種廣泛行爲。著名建築師Frank Gehry的草圖可謂天下聞名，以致於誕生了一部專門描述這些草圖的電影。他的許多建築項目都是從在一疊紙上所畫的一系列草圖開始的。Gehry總會畫上幾百張這樣的草圖，每一次都向良好的設計更靠近一步。

　　交互設計師Bill Verplank將草圖設計描述爲設計過程當中必不可少的第一步。Bill Buxton還專門寫了一整本書，用以介紹草圖設計方法對用戶體驗設計的價值，並認爲它的關鍵特徵在於它的可棄性、並且在全部探索方式中是成本最低的一種。

　　將草圖設計過程包含在API設計過程的早期階段，讓咱們有機會體驗接口的概念模型。這不只是一次定義咱們腦中已有的想法的好機會，也讓咱們有機會探索新的道路，而且提出「若是……會怎麼樣？」這樣的問題，並逐步走向真正的創新。

　　優秀的草圖應當是易於建立、而且能夠任意丟棄的。若是建立這些草圖花費了許多時間、或是難度過高，那麼你就難以丟棄它們。這種可棄性很是重要，它讓咱們有機會承受住風險。

　　咱們能夠經過草圖設計嘗試不一樣類型的接口風格，並捉住那些在咱們腦海中時而閃現的抽象概念。一旦這些思想具體化，咱們就可以對它們進行審查及討論。在過程當中決定咱們喜歡或是不喜歡某個特定的概念，而後在消化了這些知識後再次啓動這一過程，並繪製新的草圖。

　　對於設計團隊以外的用戶來講，他們不多會對草圖進行評估。不只是由於過早地對假設進行驗證是沒有價值的，而且在實際的項目中可以進行的用戶測試次數是有限的。經過真實的用戶對每種草圖都進行測試的設想代價太高，而這種方式的收穫是很是有限的。

　　使用檔案進行草圖設計

　　在進行API的草圖設計時，使用檔案（profile）或元語言（meta language）是一種很是實用的方式。檔案提供了一系列的概念，可用於草圖的設計。一個優秀的檔案能夠類比爲框與線，經過它建立系統圖的多種草圖。這些元素是設計師與評估者都可以理解的內容，它讓快速地開發草圖變得更簡單。

　　實際上，着手進行API草圖設計過程有一種好方法，就是定義接口中最明顯的單詞列表。有哪些單詞是用戶必須知道的？哪些單詞可以最好地表達你的目標受衆的目的與任務？經過回答這些問題，並建立一份接口的詞彙表，將有助於你造成對該接口的一種早期草圖。

　　檔案的美妙之處在於，它爲咱們提供了一種正規化的方式以共享及重用這種類型的信息。舉例來講，咱們在開始設計時可能會從某個XML結構文檔中提取出單詞、從schema.org獲取一份詞彙表、或者從某個ALPS或RDF文檔獲取信息，這取決於咱們的需求。

　　設計階段的目標並不是建立一份全面的詞彙表，偏偏相反，早期的詞彙表只是一個起點，咱們能夠從這一點開始繪製出其它類型的細節。咱們可能會發現一個由20個左右的單詞組成的列表就可以捕獲接口的本質，這個列表就能夠做爲咱們的起點。

　　這份詞彙表爲咱們提供了一個基礎，咱們能夠從它出發爲API中的資源與關聯設計草圖，內容能夠包括URI、資源名稱、資源間的關聯、連接文本以及其它結構化以及導航元素。請再次注意，沒有必要畫出草圖的全部細節，咱們的目標是表達出API裏最重要的部分。

　　最重要的一點在於，最初的草圖無需過於深刻。比方說，請儘可能避免在這一階段就深刻到錯誤流的建模，或響應消息元素的設計。這些部分能夠稍後再加入，或者能夠爲它們進行專門的草圖設計。

　　一份單獨的草圖無需反映出整個接口，實際上，爲某些細節部分專門設計草圖的方式可能更實用。舉例來講，咱們能夠設計一個基本錯誤流的草圖，它與整個API都具備相關性，或是設計一種響應消息格式的草圖，這種格式能夠應用到全部響應中。以後，在原型設計階段，咱們能夠將這些思想應用到某個工做模型中。

　　原型設計

　　在原型設計階段，咱們將有機會爲接口設計一個具備更高保真度的模型，而且對草圖設計階段產生的一些假設進行驗證。一個優秀的API原型應當是能夠調用的，它應當可以處理真實的請求消息，並在必要時提供響應。開發者甚至應該可以經過使用這個原型API，建立出一個簡單的應用。

　　不過，建立原型的成本應當低於一個完整的實現。有一種方法能夠保持較低的成本，即模擬響應的消息，而不是由後臺系統輸出真實的響應消息。這種方式有時也稱爲接口的虛構（mocking），它是一種創建快速原型的好方法。

　　不管使用哪一種方法創建原型，要點在於爲投入找到一個合適的範圍，可以支持後續的迭代。咱們應當可以基於草圖建立出兩至三個不一樣的原形，並在過程當中持續地學習。根據咱們在原型設計階段所學的內容，咱們甚至可能會返回草圖設計階段，並嘗試全新的方向。

　　經過原型，你的團隊將有機會得到對於設計的早期用戶反饋，而且可以對真實的使用狀況進行觀察。若是該接口的保真度已經達到了必定程度，你就可讓潛在的用戶建立應用，而且對他們在實現階段所面臨的挑戰進行觀察。

　　負責實現的成員也應當加入原形評估過程當中。一個通過良好設計的API不只應當易於使用，同時仍是可持續的、可靠的、高性能的、而且是歷時長久的。雖然接口自己不該暴露數據模型的內部細節與服務器的架構，但負責實現者爲告訴設計團隊所作的決定提供一些參考建議，例如運行環境的限制，以及實現的成本。

　　設計週期比如一個科學工藝流程，而你應當抓住原型階段的此次機會，在提出變動還爲時未晚時對所作的假設進行驗證。

　　實現

　　實現者的任務是將一個原型化的接口轉變成一種能夠放心地進行實際應用的產品。交付一個安全的、可靠的、以及可伸縮的實現是一個很大的挑戰，這一過程自己也須要經歷一種專門的設計流程。

　　最後的原型以及支持性的草圖描述了接口應該表現出的樣子，它們反映出了全部的設計決策，並造成了一份規格，說明了具體須要建立什麼樣的產品。實際上，可使用一種正式的接口描述語言（或稱IDL），從原型階段天然地過渡到實現階段。

　　舉例來講，若是你對原型API感到滿意，就能夠選擇以一種API Blueprint文檔（或Swagger、RAML、WADL，又或者是其它任何一種最適合你工做環境的格式）對其進行描述。

　　雖然這一階段的目標是實現，但也不該停下設計的腳步。這一階段是一個良機，讓你經過真實的使用數據對整個設計過程當中所作的假設進行進一步的驗證。就像原型化的API容許咱們觀察使用狀況同樣，實現後的API容許咱們在一個宏觀層面對使用狀況進行分析。

　　打個比方，你或許想對你以前所作的設計假設進行驗證。應用程序的開發者是否真的在使用你爲他們所建立的便利的操做？你是否吸引到你所指望的用戶類型？新的用戶是否在使用接口中的某些部分時遇到了麻煩？

　　通過分析，你可能會從新開始一次草圖設計過程，以準備進一步改進接口。

　　經過工具實現過程的自動化

　　工具與技術的使用會極大地改進整個設計過程。那些可以下降草圖與原型建立成本的工具可以讓設計團隊在更短的時間內建立更多的細節，使設計的決策獲得改進。

　　對於多數設計過程來講，工具與自動化的引入是一個重要的部分。在建築設計的世界中，SHoP（一個位於紐約的建築師事務所）就經過創新、合做與基於工具的設計得到了成功。他們的流程中就引入了原型工具，讓設計師可以體現出所用材料的物理特性。這種方法讓他們得以建立數以千計的設計迭代，在每次迭代中都可以體現出易於評估的實現細節。

　　在API設計的世界中，這種基於工具的優化有很好的表現機會。實際上，在服務描述領域中，已經出現了一些卓越的Web API設計工具。

　　接口描述語言也可以提供支持性的工具，以簡化編寫描述的任務，這一點如今已經很常見了。這些編輯器工具可以縮短基於IDL的設計的建立時間，所以在更短的時間內建立更多的描述也變得更容易了。Swagger、RAML與Blueprint都提供了優秀的編輯工具以支持各自的語言。即便像WADL這樣僅做爲規範發佈的IDL，也可以從SoapUI這樣的工具中受益。

　　Apiary爲Blueprint語言所提供的編輯器有很強的競爭力，由於它提供了一套完整的工做流工具以支持設計過程。只要以Blueprint編寫一個簡單的API描述，設計師就可以對文檔進行評估、調用原型，甚至對調用過程進行分析。

　　不過，這些現有的工具中的大部分都只限於其所支持的描述語言。設計者必須理解IDL的語法，而且用這種語言設計界面。雖然這種設計風格可以吸引熟悉編程語言的使用者，但也會限制在早期的草圖設計階段頗有價值的抽象與實驗性的思考方式。

　　因爲IDL及其對應工具的這些特徵，它們很適用於原型設計過程，但對於草圖設計的早期實驗性活動來講實用性不高。

　　使用可視化工具進行草圖設計

　　人們對於使用可視化工具幫助他們進行API設計的興趣正在不斷升溫。這些工具並不是直接支持編輯IDL的行爲，而是讓設計者可以隨意擺弄接口的一個可視化展示。

　　可視的建模工具提供了一種接口描述語言，這種語言多數是關於繪畫的，或是基於圖形的。雖然這個視角限制了接口展示的準確度，但它也讓設計者可以在一個較高層次看到這個接口的全貌。這一點帶來了進行改進的機會，而這種機會在手寫的形式中每每並不明顯。

　　易於使用的可視化編輯器也是進行自動化草圖設計的良好選擇，它綜合了低保真度、抽象的展示以及可棄性等特徵，這正是咱們所需的。

　　我參與開發了一個名爲Rápido!的可視化建模工具，用於輔助API的草圖設計。Rápido將用戶限制在一個低保真度的細節中，這一點並不是它的反作用，而是自己就是如此設計的。用戶可使用它進行檔案、導航元素以及響應數據的建模，但不能用於設計邏輯流程或動態的響應。

　　當設計者開始建立一個新的Rápido項目時，他們須要爲API設計一個詞彙表。在獲得一個初始的單詞列表（或者從外部導入一個ALPS詞彙表）以後，設計師就能夠在一個超媒體畫布中開始爲API設計概念模型、建立資源、嘗試URI名稱甚至是連接的狀態。

　　最終，設計者能夠爲草圖中的每一個資源或狀態實現靜態的響應消息，以增長保真度。最後，當草圖設計階段結束後，能夠將整個設計導出成IDL格式，準備在原型階段導入高保真度的工具。

　　Rápido的目標是在Web API設計的領域中提供一種快速繪製的「雞尾酒餐巾」式的草圖的體驗。若是你選擇了適當的保真度，而且沒有施加過於強烈的限制，那麼它就可以成爲API設計工具鏈中的重要一環。

　　在迭代過程當中取得成功

　　若是你按照本文中所描述的方式進行迭代式風格的設計，那麼你將爲團隊帶來一個設計高效API的良機。在過程的一開始建立多個低保真度的設計並進行評估，以培育實驗能力與構思能力。而後建立高保真度的原型以及虛擬的實現，以評估早期的設計思想。最後，爲真實用戶實現整個設計，並獲取數據以分析實際應用中的使用狀況。

　　迭代式設計過程的特定細節取決於你的環境與項目，須要多少細節、多少次迭代、以及須要哪些評估技術，這些問題將留給設計者進行回答。但做爲一種通用的經驗法則，隨着你的設計過程的推移，迭代的數量應當逐步減小，而在評估方面須要投入更多的精力。

　　優秀的API設計過程爲你提供了一個建立最佳的接口的機會。但建立優秀API的祕密並不在於專家的指導或什麼神祕的知識，而是一種經過優秀的工具、語言以及檔案所優化的迭代流程的應用而實現的。使用這個公式所交付的API定能幫助你的組織得到成功。

http://kb.cnblogs.com/page/527814/