絕佳的API設計秘訣 - DZone整合

banq發表於2019-09-11
API

我們構建軟體的方式正在發生變化。
現在，由於API平臺的激增，公司將以更快的速度推出市場並以前所未有的速度構建功能。
API經濟近年來爆炸式增長，數以千計的新API進入市場並重塑了開發人員構建軟體的方式。幾乎所有需求都有API解決方案：支付API，通訊API，運輸API以及數千種。那麼如何構建一個在競爭中脫穎而出的API呢？
無論您的目標是構建開源API，API平臺還是API，以幫助其他開發人員與您的產品整合，有一件事使成功的API脫穎而出：您必須構建一個針對開發人員最佳化的API經驗（DX）。
無論您是產品經理，技術聯合創始人還是開發人員，您都需要將終端使用者置於每個API設計決策的最前沿。透過採用這種心態，您正在為自己的使用者配備使用您的服務進行創新。Facebook就是一個很好的例子。在Facebook的早期，開發人員正在他們的平臺上構建遊戲，但Facebook從他們的努力中獲利 - 所有這些都是因為他們在社交媒體遊戲平臺內發展了一個強大的開發者社群。
透過授權他們構建自定義的應用程式體驗（甚至是您不瞭解您的平臺可以提供的體驗），將您的API使用者置於駕駛員的位置，使您在不斷髮展和變化的SaaS解決方案中脫穎而出。
在本文中，我們將討論API設計的以下方面：
  1. 縮短價值時間
  2. 將您的文件視為您網站的主頁
  3. 在您的API中使您的抽象一致
  4. 面向未來的API
  5. 改變是不可避免的，妥善管理

但在我們深入研究之前，值得一提的是每個API的這些桌面功能。由於這些相當簡單，我們不會在本文中深入探討它們：
  • 您的API應始終開啟（99.9％正常執行時間或更高）
  • 您的API應該快速閃爍（保持響應時間較短）
  • 您的API應無縫更新（無重大更改）
  • API應該暴露構建塊，而不是靜態解決方案

那些下來？好的，讓我們進入！

1.縮短價值實現時間
一個出色的API將縮短開發人員的價值實現時間（TtV）（即，他們從API中看到價值的時間）。即使在開發人員開始與您的API整合之前，也會縮短TtV。您可以透過允許使用者在文件中測試cURL響應來證明您的API在文件中的價值 - 您可以在Nylas文件中看到這樣的示例。
即使您提供測試令牌，使用第一次 - 每次一次的框架也很重要。使用測試令牌示例，大多數開發人員希望測試令牌程式完全按照規定工作，而其他人則不熟悉cURL命令的操作方式。這是優秀文件發揮作用的地方。
（1）匹配使用者的期望
在構建API時，請牢記一個問題：它是否完全符合使用者期望在第一次嘗試時執行的操作？
在大多數情況下，這需要在API的可用性方面採取“第一次做正確的事”的方法。您可以透過提供一個API來縮短您的價值實現時間（TtV），該API可以從第一次互動開始快速有效地解決具有挑戰性的技術問題。定期檢查以測試您的API，並確保第一次互動順利，並有一個很大的“哇”的感覺。

（2）使用SDK提高效率
SDK是減少整合過程中摩擦的最佳方法之一。確保開發人員能夠儘快找出API SDK整合的引數至關重要。效率既可以節省編碼時間，又可以消除任何心理障礙，同時瞭解API如何在其選擇的框架內執行。使用簡單的Ruby，NodeJS或Python SDK，開發人員可以在很短的時間內構建功能齊全的整合。
雖然SDK需要時間來建立和維護，但它們可以顯著改善開發人員體驗並降低TtV。

2.將您的文件視為您網站的主頁
將您的API文件視為您網站的首頁。它是使用者書籤和開始使用的中心位置; 它應該是使用者友好的，直觀的，並遵循邏輯流程。
您的API文件需要具有內在的可發現性和易用性 - 就像API本身一樣。Stripe是一個很好的例子。它的文件易於導航，左側邊欄上有清晰的目錄，以及透過Stripe API成功收取付款的簡單6步流程。
雖然確保API可用性和TtV快速做有價值的基礎非常重要，但您的介面只能與文件一樣可用。只有在文件易於發現時，您的文件才有用。
您的文件庫應該以內建搜尋功能的一致方式進行組織 - 特別是如果您的API中有許多需要全面文件的複雜元素。這意味著您的文件必須在邏輯上進行組織，可掃描，並在整個API整合過程中提供上下文覆蓋。
您的文件不僅應該是可發現的，而且還應該是上下文的。換句話說，它們應該出現在每個開發人員選擇的程式語言中。列出有關如何使用API​​的所有技術指南是不夠的，您需要提供可幫助為特定開發人員方案提供上下文的路標。換句話說，在建立文件時，您需要使用各種可用性。這甚至可能意味著調整您的技術以滿足每個使用者的技術需求（SDK，自定義程式碼語言）。
很可能，開發人員正在使用您的技術來解決一個獨特的問題，因此他們需要檢視各種指南，示例和快速入門，以向他們展示證明他們可以以非常具體，可擴充套件的方式使用您的API 。

3.使抽象一致
開發人員友好的API需要一致性。為了最佳化可用性，您應該建立在API中始終抽象創意的工作流程。
您還可以使用相同的POST請求在Google和Exchange事件上獲得完整的CRUD。程式碼中沒有例外，要求開發人員以不同的方式工作，儘管Google和Exchange事件的資料模型差別很大。
另一方面，很容易過於關注一致性，這樣你就會錯失創新的機會。例如，可以延遲推出API的異常，這些異常可能會以抽象一致性的名義改進您的產品，因此請務必找到合理的平衡點。

4.面向未來的API
今天，世界傾向於透過JSON移入和移出資料。取決於您的受眾，可能會有所不同，並且在幾年內可能會有所不同。新增GraphQL API可能更好。
開發人員會檢視您的API以消除其工作流程中的摩擦。如果您的API不遵循開發領域最新的無摩擦趨勢，您將失去很多興趣。雖然軟體工程的趨勢在不斷髮展，但您希望至少了解發展趨勢並考慮將哪些趨勢納入您的API。例如，大多數開發人員期望來自cURL命令的JSON響應。JSON可能看起來像是明顯的反應，但情況並非總是如此。
透過傳送簡單的JSON響應代替二進位制XML和SOAP，我們能夠最小化摩擦並建立更好的開發人員體驗。

5.變化是不可避免的 - 你如何管理它
構建API時，更改是不可避免的。REST API是GRAPH API的前身。JSON是現代API的行業標準檔案格式，但隨著技術的發展，這可能會發生變化。由於改變是不可避免的，你唯一能做的就是擁抱它並嘗試透過以下方式做好準備：

（1）從第1天開始內建版本控制
創新的數字支付提供商Stripe採用相當嚴格的方法來改變每次需要更改時建立API的新版本（有效地改變API的舊版本）。這要求它支援Stripe API的每個版本，從最初的概念到最新的推出。如果倉促或不正確地對API進行重大更改會產生嚴重的業務影響，這就是為什麼有些公司選擇與Stripe相同的版本控制方法。

（2）儘早和經常溝通變化
另一方面，Facebook快速而頻繁地對其API進行更改 - 這讓全世界的網路和移動應用程式開發人員感到高興和/或懊惱。它非常善於提前傳達這些變化（或者至少比平均值更好），因此開發人員可以做好準備，因此很少甚至沒有變化會破壞終端使用者的服務。如果您沒有資源來構建像Stripe這樣的版本化系統，那麼能夠很好地溝通變更是一種較低預算，較小規模的處理方式。
API版本控制可能具有不同的複雜程度。簡單版本編號系統（V1,1.1,1.2及以後版本）可以很好地和相當有效地擴充套件。
 

相關文章