【51CTO.com快譯】如今，隨著我們構建軟件方式的變化，以及API平臺的爆炸式激增，各大公司都必須以更快的速度構建出自己的產品、并推向市場。目前，幾乎所有的軟件需求都需要通過API來提供相應的解決方案，其中包括：支付類API、通信類API、以及傳輸類API等數千種。那么我們該如何設計并構建出一個優質的API呢?

無論您的目標是要構建一個開源的API、一種API平臺(https://dzone.com/articles/what-is-an-api-platform)、還是能幫助其他開發者與自己的產品相集成的API，您都必須努力優化開發者的API體驗(DX)。

[[276897]]

無論作為產品經理，還是技術開發人員，您都需要在每個API的設計決策上，充分考慮到最終用戶，只有這樣他們才會愿意使用您開發出的API。在此方面，Facebook就是一個非常好的例子。在早期，他們在社交媒體的游戲平臺上就開辟了一個強大的開發者社區，以方便大家構建出不同的游戲。當然Facebook也能夠從中獲利。

為了能夠在不斷變化與發展的SaaS環境中脫穎而出，您可以通過授權用戶構建自定義的應用程序(甚至是在您所不了解的平臺上提供完美的使用體驗)，來讓他們產生所謂“駕馭的快感”。

一般而言，普通API應當具有如下基本特性：

• 具有一定的魯棒性，以保證99.9%(或更高)的正常運行時間
• 具有快速響應能力，或響應耗時較短
• 能夠無縫更新，或無需引入重大變更操作
• 能夠公布各個構建的模塊，而非一個靜態固化的解決方案

下面，我們將和您深入討論設計優質API所應當注意的五個方面：

1. 縮短寶貴的時間
2. 將您的文檔置于網站的主頁
3. 在API中保證抽象的一致性
4. 設計面向未來的API
5. 妥善管理好潛在的變更

1.縮短寶貴的時間

一個優質的API應當能夠縮短開發人員的寶貴時間(TtV)。也就是說，在開發人員開始與您的API集成之前，就能夠根據對應的用戶手冊，測試有關cURL(譯者注：一種利用URL語法，工作在命令行里的文件傳輸工具)的響應，以證明API自身的使用價值。您可以在Nylas文檔(https://docs.nylas.com/reference)中，找到類似的示例。

即使您能夠提供測試令牌(test tokens)，使用一通百通(first-time-every-time)的框架也非常重要的。通過使用測試令牌的相關范例，那些不熟悉cURL命令操作的開發人員，也能夠像其他人那樣來測試令牌的進程，檢查API是否能夠完全按照設定運行下去。此處正好需要配有良好的文檔說明。

符合用戶的期望

在構建API時 ，請牢記一個問題：該API是否完全符合，用戶期望在第一次嘗試時所執行的操作?

在大多數情況下，您需要在API的實用性方面采取“首次把將正確的事做對(do the right thing right the first time)”的方法，以保障所提供的API的確能夠縮短開發者寶貴的時間(TtV)。從開發人員第一次交互開始，該API就能夠快速有效地解決那些具有挑戰性的技術問題。因此，請定期檢查并測試自己的API，確保用戶能夠順利地完成首次互動，并為后續使用樹立信心。

使用SDK來提高效率

SDK是減少集成過程出現“摩擦”的合適方法之一。它對于確保開發人員能夠盡快地找出API中的SDK集成參數，也是非常重要的。通過使用簡單的Ruby、NodeJS或Python SDK，開發人員可以在較短的時間內，了解API是如何在其選擇的框架內運行的，進而高效地完成功能齊備的集成。記住：雖然SDK需要花費一定的時間來創建和維護，但它們的確能夠顯著地改善開發人員的體驗、并降低他們的TtV。

2.將您的文檔視為網站的主頁

由于在您的首頁上就能獲取API的相關文檔，因此開發人員可以將其加入瀏覽器的書簽、或放置到顯著的位置。當然，您的API文檔不但要直觀且用戶友好，而且要能夠遵循一定的邏輯流程。

說到API文檔的易獲取性和易用性，Stripe(https://stripe.com/)就是一個很好的例子。如下圖所示，它的文檔易于導航，左側邊欄上有著清晰的目錄，右側則是Stripe API成功付款的簡單6步流程：

如果您的API中有許多需要全面進行文檔解釋的復雜元素，那么您的文檔庫應該通過內置的搜索功能，方便開發人員進行遍歷查詢。同時文檔也應當以一致性的方式進行邏輯性組織，并在整個API集成的過程中做好針對上下文的內容覆蓋。

此處的“上下文”是指，讓每一位開發人員都能選擇不同的編程語言。可見，列出針對某一種語言的API使用技術指南是不夠的，您的文檔需要具有不同語言的適用性，甚至是滿足某些特定開發技術(各種SDK、或自定義代碼語言)的解決方案。畢竟，某位開發人員很可能正在使用您的API技術，去解決某個獨特的問題，因此他們需要查看與之相關的各種指南、示例、以及快速入門。同時，這也是展示與證明您的API具備全面性和可擴展性的良機。

3.在API中保證抽象的一致性

為了方便開發人員的使用，并提高API的實用性，您需要在API中保證抽象工作流的一致性。

您可以使用相同的POST請求，在不同的Google和Exchange事件中獲得完整的CRUD(增加Create、讀取Read、更新Update和刪除Delete)。盡管Google和Exchange不同事件的數據模型差別較大，但是開發人員沒有必要以不同的方式，來開展代碼的編程工作。

當然，您不必過于苛求抽象的一致性，而刻意忽略了個別特例。例如，您可能為了顧及產品的通用一致性，而未能及時地拋出在某種環境下API的異常信息，導致開發人員無法跟蹤到程序的某項缺陷。因此，請務必找到一個合理的平衡點。

4.設計面向未來的API

[[276898]]

如今，業界傾向于通過JSON來導入和移出數據。但是在不久的將來，大家也許會大量使用到GraphQL API(譯者注：既是一種可用于API查詢的語言，又是一種滿足數據查詢的運行時)。開發人員通過檢查您的API，以消除其工作流程中的各種“摩擦”。因此，如果您的API無法遵循開發領域的最新無摩擦(frictionless)趨勢的話，那么您的API很可能會失去競爭力。例如，雖然大多數開發人員期望用JSON來響應cURL的命令。但是您可以做得更加豐富一些。通過發送各種簡單的JSON響應，來代替二進制的XML和SOAP，這樣不但能夠最小化摩擦，還能夠為開發人員創造更好的體驗。

5.妥善管理好潛在的變更

在構建API時，更改往往是不可避免的。由SOAP API引出了REST API，而REST API則是GRAPH API的前身。JSON雖然是如今API的行業標準化文件格式，但隨著技術的發展，面對任何可能出現的變化，你需要從如下方面來妥善管理自己的API：

從第1天開始就內置版本控制

創新的數字支付提供商Stripe就采用了相當嚴格的管控方法。為了避免由于倉促或不正確的API變更，對于業務產生的嚴重影響，他們從最初的概念到最終的推出，都實施了嚴格的Stripe API版本控制，并保證向后兼容性。在具體實踐中，您對于API的版本控制可能不如成熟企業那樣復雜和專業，但是您完全可以使用簡單的版本編號系統(如：V1、V1.1、V1.2等)，來更好地、有效地實現版本擴展與管控。

盡早和經常性地溝通變更

另一方面，作為業界的大廠，Facebook頻繁地對其API進行著變更和調整，這讓全世界的網絡和移動應用開發人員經常愛恨交織。不過，Facebook每次都會提前通知此類變更。因此只要您的開發人員能夠提前做好準備，就不至于被動地影響到最終用戶的服務。可見，如果您沒有實力來構建版本控制系統的話，應盡早且經常性地與各個方面溝通變更信息，這是一種更低成本、更靈活主動的處理方式。

總結

綜上所述，您需要確保自己的API在第一次被試用時就能如期運行，并籍此建立與各類開發人員的信任基礎與使用愿望。這雖然聽起來極其簡單，但是在實踐中也充滿了挑戰。希望上述五種實踐“秘籍”，能夠幫助您構建屬于自己的優質API，并能給開發者帶來不俗的體驗。

原文標題：Secrets to Great API Design，作者：Tasia Potasinski

【51CTO譯稿，合作站點轉載請注明原文譯者和出處為51CTO.com】