對於試圖完善其 API 策略的團隊來說，良好的 API 設計是一個經常出現的話題。

API 設計的重要性相信不需要贅述，精心設計的 API 的好處包括：更好開發人員體驗、更快的文件編制以及更高的 API 使用率。

那麼好的API設計到底是什麼？這篇文章將詳細介紹一些設計 RESTful API 的最佳實踐。

| 精心設計的 API 的特徵

一般來說，一個有效的 API 設計將具有以下特點：

*** 易於閱讀和使用。**一個設計良好的 API 通常都易於使用，並且它的資源和相關操作可以被不斷使用它的開發人員快速記住。

*** 難以濫用。**實現和整合具有良好設計的 API 是一個直截了當的過程，出現程式碼編寫不正確的可能性會更小。它具有資訊性反饋，並且不會強迫 API 的最終使用者遵守嚴格的規範。

*** 完整而簡潔。**最後，完整的 API 能讓開發人員針對公開的資料製作成熟的應用程式。大多數 API 設計人員和開發人員會在現有 API 的基礎上逐步構建，使應用程式的完整性隨時間推移而提高。這是每個擁有 API 的工程師或公司在努力實現的目標。

接下來的部分會以照片共享應用程式為例，說明一些概念。該應用程式允許使用者上傳照片，用這些照片的拍攝地點和描述與之相關的情緒的主題標籤來表述。

| 集合、資源及其 URL

瞭解資源和集合

資源是 REST 概念的基礎，它是一個非常重要的物件，可以被自身引用。資源具有資料、與其他資源的關係以及對其進行操作以允許訪問和操作相關資訊的方法。

一組資源稱為一個集合。集合和資源的內容取決於組織機構和使用者的要求。例如，如果某組織認為自身某產品使用者群的基本資訊可以為組織帶來利益，就可以嘗試將其作為集合或資源公開，比如像qq在內的各種快捷登入。

統一資源定位符 (URL) 標識資源的線上位置。此 URL 指向 API 資源所在的位置。base URL 是此位置的一部分。

在照片共享應用程式中，我們可以通過適當的 URL 訪問的集合和資源公開有關使用該應用程式的使用者的資料。

名詞可以更好地描述 URL

base URL 應該整潔、優雅且簡單，以便使用該產品的開發人員可以輕鬆地在他們的 Web 應用程式中使用它們。一個又長又難讀的基本 URL 不僅不好看，而且在嘗試重新編碼時也容易出錯。以名詞命名 URL 應該始終被作為最優解。

我們在設計時，通常沒有關於保持資源名詞單數或複數的規範，但建議保持集合複數。在所有資源和集合中分別使用相同的複數是一種很好的做法，可以保持描述的一致性。

保持這種命名方式，有助於開發人員理解URL所描述的資源型別，方便他們快速使用這些 API。

說回照片共享應用程式，假設它有一個公共 API，其中包含 /users 和 /photos 作為集合。一目瞭然，這些都是複數的名詞。由此我們可以推斷出 /users 和 /photos 分別提供有關產品註冊使用者群和共享照片的資訊。

使用 HTTP 方法描述資源功能

所有資源都有一組可以針對它們進行操作的請求方法，用以處理 API 公開的資料。

RESTful API 主要由 HTTP 請求方法組成，這些請求方法對任何資源具有明確定義的獨特操作。以下是常用 HTTP 請求的列表，這些請求定義了 RESTful API 中任何資源或集合的 CRUD 操作。

將動詞排除在 URL 之外是一個好主意。GET、PUT、POST 和 DELETE 操作已用於對 URL 描述的資源進行操作，因此在 URL 中使用動詞而不是名詞會使處理資源變得混亂。

在照片共享應用程式中，以 /users 和 /photos 作為端點，API 的最終使用者可以使用上述 RESTful CRUD 操作輕鬆直觀地使用它們。

| 響應

提供反饋以幫助開發人員取得成功

在開發人員使用產品時，提供的良好的反饋響應，對提高使用率和留存率大幫助極大。每個客戶端請求和伺服器端響應都是一條訊息，在理想的 RESTful 生態系統中，這些訊息必須是自描述的。

好的反饋包括對正確實現的自動驗證，以及對不正確實現的詳細報錯。這可以幫助使用者除錯和糾正他們使用產品的方式。

調整錯誤可以使用標準 HTTP 程式碼。對於報錯，客戶端呼叫應該有對應的 400 型別的錯誤程式碼與之關聯；如果存在任何伺服器端錯誤，則必須將對應的 500 響應與它們相關聯。使用資源的成功請求方法，應返回 200 型別的響應。

一般而言，使用 API 時會出現三種可能的結果：

*** 客戶端應用程式執行錯誤（客戶端錯誤 – 4xx 響應程式碼）。**

*** API 行為錯誤（伺服器錯誤 – 5xx 響應程式碼）。**

*** 客戶端和 API 工作（成功 - 2xx 響應程式碼）。**

當使用者在使用 API 遇到障礙時，引導他們成功完成，這將大大有助於改善開發人員體驗和防止 API 濫用。而很好地描述這些錯誤響應，需要保持簡單和整潔。除了這些，還需要在錯誤程式碼中為最終使用者提供足夠的資訊，才能幫助他們開始修改調整，如果覺得簡單描述不夠，那可以再提供指向其他文件的連結。

舉例說明所有的 GET 響應

一個設計良好的 API 應當有對應的例子，對一個URL獲得成功的響應。此示例響應應該簡單、明瞭且易於理解。一個好的經驗法則是幫助開發人員在五秒內準確瞭解成功的響應會給他們帶來什麼。

回到我們的照片共享應用程式，我們定義了一個 /users 和一個 /photos URL。/users 集合將在陣列中提供所有已註冊應用程式的使用者的使用者名稱和加入日期。

可以使用像 Eolink 這樣的 API設計開發工具，在 OpenAPI 規範中定義 API，如下所示：

請注意終端使用者可以從成功的 GET 呼叫中獲得的每個響應項中描述的資料型別和示例。終端使用者將接收JSON 格式的成功響應如下所示。

如果終端使用者使用 GET 方法成功呼叫終端點，那麼使用者應獲取上述資料以及 200 響應程式碼來驗證此為正確用法。同樣，不正確的呼叫，應反饋對應的 400 或 500 響應程式碼以及相關資訊，以幫助使用者更好地對集合進行操作。

| 請求

優雅地處理複雜的問題

嘗試公開的資料可以通過許多屬性來展示，這些屬性可能對使用該 API 的最終消費者有益。這些屬性描述了基本資源並隔離了可以使用適當方法操作的特定資訊資產。

API 應儘量保證完整度，並提供所有必需的資訊、資料和資源，以幫助開發人員以無縫方式與它們整合。

但是，完成度意味著要考慮 API 的常見用例。可能有無數的情景關聯和屬性，去定義它們中的每一個資源並不是一個好的做法。

還應考慮資源公開的資料量。如果試圖加載出來很多資料，可能會對伺服器產生負面影響，尤其是在負載和效能方面。

上述情況和關係是 API 設計中的重要考慮因素，可以使用適當的引數進行處理。可以掃描屬性並限制查詢引數中“?”後面的響應，或者使用路徑引數隔離客戶端正在使用的資料的特定元件。

讓我們以我們的照片共享應用程式為例。

開發人員可以使用它來獲取有關在特定位置和特定主題標籤共享的所有照片的資訊。我們還希望將每個 API 呼叫的結果數限制為 10，以防止伺服器負載。如果終端使用者想要在波士頓找到帶有 #winter 標籤的所有照片，呼叫將是：

請注意，複雜的問題現在已被簡化為與查詢引數的簡單關聯。如果您想根據客戶的請求提供有關特定使用者的資訊，則呼叫將是：

其中 kesh92 是 users 集合中特定使用者的使用者名稱，將返回 kesh92 的位置和加入日期。

以上是一些可以設計引數以實現 API，完成並幫助開發人員直觀地使用 API 的一些方法。

最後，如果對特定資源或集合的功能有第二個想法，請將其留待下一次迭代。開發和維護 API 是一個持續的過程，等待合適使用者的反饋有助於構建強大的 API，使使用者能夠以創造性的方式整合和開發應用程式。

圖中所使用的的介面管理工具是eolink，感興趣可以自行使用：www.eolink.com