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

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

[[276897]]

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

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

一般而言，普通API應(yīng)當具有如下基本特性：

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

下面，我們將和您深入討論設(shè)計優(yōu)質(zhì)API所應(yīng)當注意的五個方面：

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

1.縮短寶貴的時間

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

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

符合用戶的期望

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

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

使用SDK來提高效率

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

2.將您的文檔視為網(wǎng)站的主頁

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

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

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

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

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

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

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

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

4.設(shè)計面向未來的API

[[276898]]

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

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

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

從第1天開始就內(nèi)置版本控制

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

盡早和經(jīng)常性地溝通變更

另一方面，作為業(yè)界的大廠，F(xiàn)acebook頻繁地對其API進行著變更和調(diào)整，這讓全世界的網(wǎng)絡(luò)和移動應(yīng)用開發(fā)人員經(jīng)常愛恨交織。不過，F(xiàn)acebook每次都會提前通知此類變更。因此只要您的開發(fā)人員能夠提前做好準備，就不至于被動地影響到最終用戶的服務(wù)?？梢姡绻鷽]有實力來構(gòu)建版本控制系統(tǒng)的話，應(yīng)盡早且經(jīng)常性地與各個方面溝通變更信息，這是一種更低成本、更靈活主動的處理方式。

總結(jié)

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

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

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