一文詳解 API 設計最佳實踐

-     前言    -

良好設計的 API = 快樂的程序員 😃。

應用程序接口（API）是一種接口，它讓應用程序可以輕鬆地使用另一個應用程序的數據和資源，API 對於一個產品或公司的成功至關重要。

如果沒有 API，你大部分喜歡的軟件今天就不會存在。例如，Google Maps API 可以讓你在 app 或 Web 應用中使用 Google Maps。如果沒有它，你將不得不設計和開發自己的地圖數據庫。這樣的話，在地圖上顯示一個位置需要花費多少時間？

爲什麼要使用 API？

  1. API 可以讓外部應用訪問您的資源

  2. API 擴展了應用程序的功能

  3. API 允許開發者重用應用邏輯

  4. API 是獨立於平臺的，它們傳遞數據不受請求平臺的影響

在大多數實際場景中，數據模型 已經存在，但由於我們將討論 API 設計最佳實踐，我將從頭開始說起。

-     數據建模與結構化    -

以 API 爲中心對您的數據進行建模，是設計易於創建、維護和更新 API 的第一步

在設計 API 時，儘量考慮使用通用的術語，而不是使用內部的複雜業務術語，因爲這些術語在公司外可能不爲人所知。你的 API 可能會對外開放，以允許外部開發人員使用你的 API 開發他們自己的應用。通過使用通用術語，你可以確保使用 API 的開發人員易於瞭解你的 API，並能快速上手。

假設到你正在建立一個門戶網站，讓用戶點評不同作者的書籍。你的公司可能會使用特定的術語，如創作者、創作、系列等來指代圖書作者、書籍和系列。但爲了簡單起見，並方便外部應用開發者使用你的 API，使用通用的概念而不是公司特定的術語來創建 API 路徑。

https://api.domain.com/authors
 https://api.domain.com/authors/{id}/books

這有助於新的開發人員快速瞭解你的 API 是什麼，以及如何遍歷你的數據模型。

-     編寫面向資源的 API    -

應用程序需要訪問你的資源。維護一個資源層次結構可以幫助你更好地構建 API。資源層次結構是指路徑中的每個節點，它由一個集合或一個資源組成。

資源可以是一個單一的數據，例如，上面例子中的作者簡介。

集合是指一個資源的集合，在我們的例子中，它可以是一個作者所寫的書的列表。

合適的資源層次結構可以是：

Base Path -> 作者 (集合) -> profile (資源)
Base Path -> 作者 (集合) -> 書 (集合) -> 書 (資源)

層次結構需要保持一致，以確保開發人員在將其應用程序接入 API 時遇到的問題最少。

爲了保持簡單性和一致性，這裏有一些指導原則可以幫助你：

  1. 命名集合和資源時使用美式英語（例如：color 而不是 colour）

  2. 避免拼寫錯誤

  3. 使用更簡單、更常用的詞來保持清晰，例如 delete 而不是 remove

  4. 如果你使用的資源與其他 API 使用的資源相同，請使用相同的術語以保持一致。

  5. 對集合使用複數形式（例如：authors、books 等）。

-     RESTful 接口    -

HTTP 形式的 API 最廣泛接受的標準是 REST(Representational State Transfer)。它基本上意味着每個 URL 代表一個對象。

API 目的可以是以下之一：

  1. 創建數據 Create

  2. 讀取數據 Read

  3. 更新數據 Update

  4. 刪除數據 Delete

CRUD！猜對了!

API 通過使用一組 HTTP 命令來處理，這些命令定義了請求的性質和它應該做什麼。

GET 從 API 中檢索數據。它要求從 API 中獲取數據的表示。GET 請求可以包含查詢參數，以過濾從 API 接收的結果。

POST 向 API 提交一條記錄，該記錄將在數據庫中創建一個資源。

PUT 一般用於更新服務器上的現有資源。

DELETE 從服務器上刪除一個資源。

-     API 版本控制    -

應用程序和 API 的生命週期越長，應用和 API 對用戶的承諾就越大。在某個時間點上，你的 API 將需要修改，因爲你無法預見隨着需求和業務政策而發生的變化。

因此需要對 API 進行更改。但是 API 可能已經有一個或多個開發者在使用了，所以，重要的是，你所做的更改不會破壞你的合作伙伴開發者的應用。

-     瞭解主要和次要更新    -

小版本升級（Minor）：當變更不會破壞客戶端應用程序的運行時，可以使用小版本升級，例如添加可選字段或支持附加參數。這時候你可以爲你的 API 增設小版本。

大版本升級（Major）：是那些肯定會破壞現有客戶端應用的版本，比如在請求參數中添加一個新的必需參數，或改變返回結果中的字段。

可以通過多種方式來對 API 進行版本控制。

最常見的方法是將版本包含在 URI 中。

https://api.domain.com/v1.0/authors

另外一種方法是使用基於日期的版本控制。URI 中包括將版本發佈日期。應用程序開發人員可以很方便了解 API 更改的頻率。

https://api.domain.com/2020-06-15/authors

另一種方法是在請求標頭中包含 API 版本。

https://api.domain.com/authors
 x-api-version：v1

最推薦和接受的版本控制方式是，在 URI 中使用版本名稱。

-     分頁    -

在數據量越來越大的世界裏，不可能在一個屏幕上同時顯示所有的數據。所以，讓用戶在再次請求數據之前，先取到一定數量的結果，這一點很重要。這就是所謂的分頁，返回的數據集叫做頁面。

建議你在請求和返回結果中使用特定的術語來啓用 API 中的分頁功能。這些術語有

  1. STRING page_token（在請求中發送）

  2. STRING next_page_token（由 API 返回）

  3. INT page_size（在請求中發送）

page_token 請求 API 需要返回哪個頁面。這通常是一個字符串。對於第一次 API 調用，page_token = "1"

page_size 定義了返回結果中應該返回多少條記錄。例如 page_size = 100，在 API 調用中最多返回 100 條記錄。

next_page_token 定義了翻頁的下一個 token。如果在 page_token = "1" 之後有額外的數據，返回的值是應當是  next_page_token="2"

如果沒有更多的數據可用，而且用戶已經到達數據的終點，則返回一個空白值 next_page_token="" 。

這些就是設計 API 的最佳實踐。它讓你的 API 更健壯、簡潔並易於與其他應用程序集成。

請記住。

良好設計的 API = 快樂的程序員 😃。

作者：Varun Joshi

來源：

https://codeburst.io/best-practices-api-design-61d4697d17ff

中生代技術

關注技術架構、研發管理、互聯網金融、電商、大數據、區塊鏈、人工智能等方向！

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/NSLS_sHpXRK6Nm3U-vh8CA

猜你喜歡