要想設計出可以正常運行的Web API，對基于web的應用的基本理解是一個良好的基礎。但如果你的目標是創(chuàng)建出優(yōu)秀的API，那么僅憑這一點還遠遠不夠。設計優(yōu)秀的API是一個艱難的過程，如果它恰巧是你當前的工作任務，那么你很可能會感到手足無措。

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

優(yōu)秀的API設計來自于迭代過程

在開始設計API之前，我們必須理解它的目的。在你手動設計之前，你應當了解為什么要設計這個API，如果在這方面需要幫助，有許多現(xiàn)成的資料可以參考。不過，定義你的動機僅僅是第一步，真正的訣竅在于直到實現(xiàn)為止，始終保持進行正確的設計決策。

成功的API設計意味著要設計出一種接口，讓它的使用方式符合它的目的。作為API設計者來說，我們所做的每個決策都會影響到產(chǎn)品的成敗。設計過程中需要做出一些重大的決策，例如API所使用的傳輸協(xié)議、或它所支持的消息格式。但除此之外，還有許多相關的次要決定，例如接口的控制、名稱、關聯(lián)以及次序。而當你將所有的決策集中在一起時，它們將帶動API的使用模式。如果你能夠做到每個決定都是正確的，那么這種模式將對API產(chǎn)生完美的支持與促進作用。

如果你要做出一個正確的設計決策，很可能會先做出一個錯誤的決策，并從中吸取經(jīng)驗教訓。實際上，你很可能會在多次犯錯之后才能夠接近正確的決策。這也正是迭代的關鍵所在，因為沒有人能夠做到一次成功，但只要有足夠的機會，你就能夠做到接近完美。

通過迭代方式進行API設計，這一點說起來容易，但在實際應用中做到這一點并不簡單。我們所面臨的一個常見的挑戰(zhàn)在于，在某個API發(fā)布之后再進行變更是非常困難的。事實上，對一個使用中的API進行變更的代價很大，并且伴隨著很大的風險?；蛘呓栌肑oshua Bloch的說法：“公開的API就像鉆石，它是永恒不變的。”

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

換種思路，我們應當在接口發(fā)布之前就做好這些變更。在理想的情況下，在變更的代價變得高昂之前，就應該消除易用性與設計方面的問題。當時，只有在首次發(fā)布之前做到盡早開始迭代，并保持頻繁的迭代，才能夠找到并修復這些問題。

迭代式的設計過程

在每一次迭代中，我們都得到了一次對設計候選按其使用情況進行評估的機會。舉例來說，開發(fā)者是否能夠通過使用我們創(chuàng)建的產(chǎn)品實現(xiàn)他的工作目標？這個接口真的能夠實現(xiàn)嗎？如果我們要求他人使用這個API，他們又會有什么樣的感受？

通過設計與實現(xiàn)多個接口而不發(fā)布它們，應該能夠實現(xiàn)最佳的API設計。通過對每個接口進行審查與測試，我們將對于如何改進最終產(chǎn)品具有良好的洞察力。

但是在實踐中，這種壯觀的迭代式設計是不可能實現(xiàn)的。沒有幾個人能有足夠的時間、金錢或耐心去不斷地設計與實現(xiàn)一個個可以運行的API。對于任何具有一定復雜度的接口來說，這種方式的迭代式設計會占用你過多的時間。

一個更合理的方式是在設計過程的早期就進行迭代，這些早期的設計應當具有足夠的細節(jié)，可展現(xiàn)改進的最佳時機，但又無需過度設計而導致實現(xiàn)的困難。隨著時間的推移，我們可以逐步地增加細節(jié)度（或保真度），并最終得到一個完整的實現(xiàn)。

這種逐步推進的設計過程在設計界已經(jīng)非常流行了，它通常被分解為三個重要的階段：

1. 草圖設計
2. 原型設計
3. 實現(xiàn)

草圖設計的強大作用

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

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

將草圖設計過程包含在API設計過程的早期階段，讓我們有機會體驗接口的概念模型。這不僅是一次定義我們腦中已有的想法的好機會，也讓我們有機會探索新的道路，并且提出“如果……會怎么樣？”這樣的問題，并逐步走向真正的創(chuàng)新。

優(yōu)秀的草圖應當是易于創(chuàng)建、并且可以任意丟棄的。如果創(chuàng)建這些草圖花費了許多時間、或是難度太高，那么你就難以丟棄它們。這種可棄性非常重要，它讓我們有機會承受住風險。

我們可以通過草圖設計嘗試不同類型的接口風格，并捉住那些在我們腦海中時而閃現(xiàn)的抽象概念。一旦這些思想具體化，我們就能夠對它們進行審查及討論。在過程中決定我們喜歡或是不喜歡某個特定的概念，然后在消化了這些知識后再次啟動這一過程，并繪制新的草圖。

對于設計團隊之外的用戶來說，他們很少會對草圖進行評估。不僅是因為過早地對假設進行驗證是沒有價值的，并且在實際的項目中能夠進行的用戶測試次數(shù)是有限的。通過真實的用戶對每種草圖都進行測試的設想代價過高，而這種方式的收獲是非常有限的。

使用檔案進行草圖設計

在進行API的草圖設計時，使用檔案（profile）或元語言（meta language）是一種非常實用的方式。檔案提供了一系列的概念，可用于草圖的設計。一個優(yōu)秀的檔案可以類比為框與線，通過它創(chuàng)建系統(tǒng)圖的多種草圖。這些元素是設計師與評估者都能夠理解的內(nèi)容，它讓快速地開發(fā)草圖變得更簡單。

實際上，著手進行API草圖設計過程有一種好方法，就是定義接口中最明顯的單詞列表。有哪些單詞是用戶必須知道的？哪些單詞能夠最好地表達你的目標受眾的目的與任務？通過回答這些問題，并創(chuàng)建一份接口的詞匯表，將有助于你形成對該接口的一種早期草圖。

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

設計階段的目標并非創(chuàng)建一份全面的詞匯表，恰恰相反，早期的詞匯表只是一個起點，我們可以從這一點開始繪制出其它類型的細節(jié)。我們可能會發(fā)現(xiàn)一個由20個左右的單詞組成的列表就能夠捕獲接口的本質，這個列表就可以作為我們的起點。

這份詞匯表為我們提供了一個基礎，我們可以從它出發(fā)為API中的資源與關聯(lián)設計草圖，內(nèi)容可以包括URI、資源名稱、資源間的關聯(lián)、鏈接文本以及其它結構化以及導航元素。請再次注意，沒有必要畫出草圖的所有細節(jié)，我們的目標是表達出API里最重要的部分。

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

一份單獨的草圖無需反映出整個接口，實際上，為某些細節(jié)部分專門設計草圖的方式可能更實用。舉例來說，我們可以設計一個基本錯誤流的草圖，它與整個API都具有相關性，或是設計一種響應消息格式的草圖，這種格式可以應用到所有響應中。之后，在原型設計階段，我們可以將這些思想應用到某個工作模型中。

原型設計

在原型設計階段，我們將有機會為接口設計一個具有更高保真度的模型，并且對草圖設計階段產(chǎn)生的一些假設進行驗證。一個優(yōu)秀的API原型應當是可以調用的，它應當能夠處理真實的請求消息，并在必要時提供響應。開發(fā)者甚至應該能夠通過使用這個原型API，創(chuàng)建出一個簡單的應用。

不過，創(chuàng)建原型的成本應當?shù)陀谝粋€完整的實現(xiàn)。有一種方法可以保持較低的成本，即模擬響應的消息，而不是由后臺系統(tǒng)輸出真實的響應消息。這種方式有時也稱為接口的虛構（mocking），它是一種建立快速原型的好方法。

無論使用哪種方法建立原型，要點在于為投入找到一個合適的范圍，能夠支持后續(xù)的迭代。我們應當能夠基于草圖創(chuàng)建出兩至三個不同的原形，并在過程中持續(xù)地學習。根據(jù)我們在原型設計階段所學的內(nèi)容，我們甚至可能會返回草圖設計階段，并嘗試全新的方向。

通過原型，你的團隊將有機會獲得對于設計的早期用戶反饋，并且能夠對真實的使用情況進行觀察。如果該接口的保真度已經(jīng)達到了一定程度，你就可以讓潛在的用戶創(chuàng)建應用，并且對他們在實現(xiàn)階段所面臨的挑戰(zhàn)進行觀察。

負責實現(xiàn)的成員也應當加入原形評估過程中。一個經(jīng)過良好設計的API不僅應當易于使用，同時還是可持續(xù)的、可靠的、高性能的、并且是歷時長久的。雖然接口本身不應暴露數(shù)據(jù)模型的內(nèi)部細節(jié)與服務器的架構，但負責實現(xiàn)者為告訴設計團隊所做的決定提供一些參考建議，例如運行環(huán)境的限制，以及實現(xiàn)的成本。

設計周期好比一個科學工藝流程，而你應當抓住原型階段的這次機會，在提出變更還為時未晚時對所做的假設進行驗證。

實現(xiàn)

實現(xiàn)者的任務是將一個原型化的接口轉變成一種可以放心地進行實際應用的產(chǎn)品。交付一個安全的、可靠的、以及可伸縮的實現(xiàn)是一個很大的挑戰(zhàn)，這一過程本身也需要經(jīng)歷一種專門的設計流程。

最后的原型以及支持性的草圖描述了接口應該表現(xiàn)出的樣子，它們反映出了所有的設計決策，并形成了一份規(guī)格，說明了具體需要創(chuàng)建什么樣的產(chǎn)品。實際上，可以使用一種正式的接口描述語言（或稱IDL），從原型階段自然地過渡到實現(xiàn)階段。

舉例來說，如果你對原型API感到滿意，就可以選擇以一種API Blueprint文檔（或Swagger、RAML、WADL，又或者是其它任何一種最適合你工作環(huán)境的格式）對其進行描述。

雖然這一階段的目標是實現(xiàn)，但也不應停下設計的腳步。這一階段是一個良機，讓你通過真實的使用數(shù)據(jù)對整個設計過程中所做的假設進行進一步的驗證。就像原型化的API允許我們觀察使用情況一樣，實現(xiàn)后的API允許我們在一個宏觀層面對使用情況進行分析。

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

經(jīng)過分析，你可能會重新開始一次草圖設計過程，以準備經(jīng)過進一步改進的接口。

通過工具實現(xiàn)過程的自動化

工具與技術的使用會極大地改進整個設計過程。那些能夠降低草圖與原型創(chuàng)建成本的工具能夠讓設計團隊在更短的時間內(nèi)創(chuàng)建更多的細節(jié)，使設計的決策得到改進。

對于多數(shù)設計過程來說，工具與自動化的引入是一個重要的部分。在建筑設計的世界中，SHoP（一個位于紐約的建筑師事務所）就通過創(chuàng)新、合作與基于工具的設計獲得了成功。他們的流程中就引入了原型工具，讓設計師能夠體現(xiàn)出所用材料的物理特性。這種方法讓他們得以創(chuàng)建數(shù)以千計的設計迭代，在每次迭代中都能夠體現(xiàn)出易于評估的實現(xiàn)細節(jié)。

在API設計的世界中，這種基于工具的優(yōu)化有很好的表現(xiàn)機會。實際上，在服務描述領域中，已經(jīng)出現(xiàn)了一些卓越的Web API設計工具。

接口描述語言也能夠提供支持性的工具，以簡化編寫描述的任務，這一點現(xiàn)在已經(jīng)很常見了。這些編輯器工具能夠縮短基于IDL的設計的創(chuàng)建時間，因此在更短的時間內(nèi)創(chuàng)建更多的描述也變得更容易了。Swagger、RAML與Blueprint都提供了優(yōu)秀的編輯工具以支持各自的語言。即使像WADL這樣僅作為規(guī)范發(fā)布的IDL，也能夠從SoapUI這樣的工具中受益。

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

(**單擊圖片以放大**)

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

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

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

人們對于使用可視化工具幫助他們進行API設計的興趣正在不斷升溫。這些工具并非直接支持編輯IDL的行為，而是讓設計者能夠隨意擺弄接口的一個可視化展現(xiàn)。

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

易于使用的可視化編輯器也是進行自動化草圖設計的良好選擇，它綜合了低保真度、抽象的展現(xiàn)以及可棄性等特征，這正是我們所需的。

我參與開發(fā)了一個名為Rápido!的可視化建模工具，用于輔助API的草圖設計。Rápido將用戶限制在一個低保真度的細節(jié)中，這一點并非它的副作用，而是本身就是如此設計的。用戶可以使用它進行檔案、導航元素以及響應數(shù)據(jù)的建模，但不能用于設計邏輯流程或動態(tài)的響應。

當設計者開始創(chuàng)建一個新的Rápido項目時，他們需要為API設計一個詞匯表。在得到一個初始的單詞列表（或者從外部導入一個ALPS詞匯表）之后，設計師就可以在一個超媒體畫布中開始為API設計概念模型、創(chuàng)建資源、嘗試URI名稱甚至是鏈接的狀態(tài)。

最終，設計者可以為草圖中的每個資源或狀態(tài)實現(xiàn)靜態(tài)的響應消息，以增加保真度。最后，當草圖設計階段結束后，可以將整個設計導出成IDL格式，準備在原型階段導入高保真度的工具。

Rápido的目標是在Web API設計的領域中提供一種快速繪制的“雞尾酒餐巾”式的草圖的體驗。如果你選擇了適當?shù)谋Ｕ娑龋⑶覜]有施加過于強烈的限制，那么它就能夠成為API設計工具鏈中的重要一環(huán)。

在迭代過程中取得成功

如果你按照本文中所描述的方式進行迭代式風格的設計，那么你將為團隊帶來一個設計高效API的良機。在過程的一開始創(chuàng)建多個低保真度的設計并進行評估，以培育實驗能力與構思能力。然后創(chuàng)建高保真度的原型以及虛擬的實現(xiàn)，以評估早期的設計思想。最后，為真實用戶實現(xiàn)整個設計，并獲取數(shù)據(jù)以分析實際應用中的使用情況。

迭代式設計過程的特定細節(jié)取決于你的環(huán)境與項目，需要多少細節(jié)、多少次迭代、以及需要哪些評估技術，這些問題將留給設計者進行回答。但作為一種通用的經(jīng)驗法則，隨著你的設計過程的推移，迭代的數(shù)量應當逐步減少，而在評估方面需要投入更多的精力。

優(yōu)秀的API設計過程為你提供了一個創(chuàng)建最佳的接口的機會。但創(chuàng)建優(yōu)秀API的秘密并不在于專家的指導或什么神秘的知識，而是一種通過優(yōu)秀的工具、語言以及檔案所優(yōu)化的迭代流程的應用而實現(xiàn)的。使用這個公式所交付的API定能幫助你的組織獲得成功。

關于作者

Ronnie Mitra是CA Technologies公司的API Academy部門的API設計總監(jiān)。他多次幫助遍布全球的組織成功地完成了API的設計與實現(xiàn)。Ronnie具有超過30年的行業(yè)經(jīng)驗，在此期間內(nèi)他不斷地在失敗中進行學習。

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