構建API的7個技巧

banq發表於2018-10-19
API

截至2018年，企業越來越依賴API來為其客戶服務。微服務和無伺服器架構正變得越來越普遍，並且建立了更多的所需API整合點，以確保競爭優勢和業務可見性。API應該從頭開始設計，並考慮到這些需求。在本文中，我將討論有助於實現這些目標的API的七個設計技巧。（我應該注意，這些見解是基於我為移動客戶端構建API的經驗，但可更廣泛地應用於任何型別的API設計。

1.將API視為產品
開發的期初關鍵因素是產品概念。它定義了獨立的實體，為市場提供有用的功能和好處。設計和實施易於消費，可擴充套件，正確記錄和保護的API並不是一項容易的任務，而且不會在過程中產生強烈的責任感和所有權。因此，將API被視為一個公平，完整的董事會，積壓和衝刺計劃是公平的。此外，還需要指定產品負責人，以便向敏捷團隊傳達理想API的願景。開發人員和測試人員必須制定計劃以使用API​​最佳實踐，並避免常見錯誤。最終產品需要從第一天開始生產。

2.使用API​​規範框架
API框架旨在標準化跨行業的開發流程。通常，它們由一系列工具組成，涵蓋從概念到生產的整個開發生命週期。雖然在開發API時堅持使用OpenAPI / Swagger這樣的規範更為明確，但它提供了更好的工具互操作性。每個人都喜歡自動化，並且每次程式碼更改時都能夠生成文件，SDK和UI互動點非常有用。如果您關心標準並希望在描述API時提供傳統工具，那麼這是一個非常可靠的選項，可以提前還清。

3.使用版本控制策略
您的API是您的產品，隨著業務需求的變化，它會隨著時間的推移而發展。作為產品，它具有特定版本，因此客戶期望得到正確的響應。更改已釋出和使用的API介面是一個定時炸彈。你想要的最後一件事是在沒有客戶知道的情況下引入重大變化。對於移動應用程式尤其如此，使用者可能仍然在其手機上安裝舊版本。有多種方法可以在API上實施版本控制資訊。大多數API設計者都選擇將版本資訊放在URL中，因為它很實用。例如，以下URL表示customer的資源端點：/ API / V1 /customer堅持適用於業務和可用工具的版本策略非常重要。稍後，如果您決定更改版本，則更容易提供警告，更新和其他機制。

4.使用過濾和分頁
開發API時的一個常見錯誤是沒有提供過濾或分頁結果的方法。當您公開返回可隨時間變化的專案列表的API時，您需要建立分頁策略。原因很簡單。客戶端，尤其是移動客戶端，無法一次檢視數百個列表項，因此您可以顯示前10個（例如）。如果您的API返回每個請求的整個資料庫列表，則會浪費大量資源並且效能會大幅下降。現代框架提供了一種分頁結果的方法，但也可以自定義自己的結果。常見的方法是在查詢中使用LIMIT和OFFSET語句。例如，請參閱此MySQL語句以返回總結果的一部分：SELECT * form customer LIMIT 5,10此語句將從資料庫中檢索第6-16行，以便您可以提供JSON響應，該響應根據LIMIT引數提供指向該查詢的第一頁，下一頁，上一頁和最後一頁的連結：
 

// _links
{
  “first”：“ / api / v1 / customers ？page = 1 “，
   ”prev“：” / api / v1 / customers ？page = 1 “，
   ”next“：” / api / v1 / customers ？page = 3 “，
   ”last“：” / api / v1 / customers ？page = 9 “ 
}


5.使用REST和HATEOAS
REST是一種經過驗證且經過實戰考驗的架構方法，用於設計Web服務，它獨立於任何底層協議。因此，它非常適合設計API。透過使用REST原則，您可以應用一些設計注意事項，例如：

  • 將端點視為具有傳統命名方案的資源。例如，如果要公開訂單列表，則公開以下端點：

GET / api / v1 /order如果要查詢特定訂單，您將提供ID引數：GET / api / v1 / orders / 1這具有幾個優點，例如更好的均勻性，可讀性和一致性。
  • 促進無狀態交易。這些有助於使服務更具可擴充套件性，因為它們不具有在客戶端和伺服器通訊之間保持狀態的硬耦合約束。
  • 在HATEOAS的幫助下，無需事先了解內部URI方案，即可在整個資源集中輕鬆導航。它透過提供一組相關連結來增強每個資源的響應模型，這樣在不查詢規範或其他後設資料服務的情況下更容易與API互動。HATEOAS的一個好格式是HAL規範。例如，這是對特定文章資源的HAL響應，公開了記者的相關連結： 


{
   “_ links”：{
     “Self”：{
         “href”：“ / api / v1 / articles / 1 ”
    }，
    “ / rels / reporter”：[
      {
        “href”：“ / api / v1 / reporter / 1121 ” 
        “fullName”：“John  Doe”
      }，
      {
        “href”：“ / api / v1 / reporter / 192 ” 
        “fullName”：“Alice  Jansen”
      }
    ]
  }
}


6.保護您的終端你不應該忽視安全。任何違規行為都可能產生災難性後果，並可能導致嚴重的法律問題。需要在開發過程的早期建立安全控制，理想情況下，您的API需要由外部供應商進行評估。在CIA安全的黑社會適用下列要求：

  • 安全性透過新增適當的身份驗證控制元件來實現，這些身份驗證控制元件為您的系統提供了一種瞭解誰正在訪問資訊或站點的方法。OAuth2和JWT提供了一種實用且安全的方法來提供此功能。必須在所有公共端點使用HTTPS以確保安全通訊。
  • 整合性是透過使用實現訪問控制和授權策略，以防止未經授權的使用者資料的篡改。基於角色的授權提供了一個很好的選擇。
  • 可用性透過建立實現速率限制，部分反應和快取，以防止API資源或無限迴圈取下來，甚至伺服器的廣泛使用。


7.使用監控和報告雖然開發和測試API在此過程中起著重要作用，但真正的工作並不止於此。甚至在將程式碼部署到生產之前，您需要繼續提供支援。如果出現問題，需要透過可操作的資訊通知合適的人員，以便以任何必要的方式作出回應。這是開發API時的主動方法。如果你把事情放在一邊，那麼當端點問題出現時，你可以防止災難性的失敗。 

相關文章