良好的 API 設計是許多團隊在嘗試完善其 API 策略時經常出現的主題。在先前的部落格文章中，我簡要討論了 API 設計的重要性。良好設計的 API 的優點包括：改善開發人員體驗、更快的文檔和更高的 API 採用率。 但是，良好的 API 設計究竟包含哪些內容？在這篇部落格文章中，我將詳細介紹一些設計 RESTful API 的最佳實踐。
良好設計的 API 的特徵
一般而言，有效的 API 設計將具有以下特徵
- 易於閱讀和使用：良好設計的 API 將易於使用，並且其資源和相關操作可以讓經常使用它的開發人員快速記住。
- 難以濫用：實作和整合具有良好設計的 API 將是一個簡單的過程，並且寫出不正確的程式碼的可能性較小。它具有資訊豐富的回饋，並且不會對 API 的最終使用者實施嚴格的準則。
- 完整且簡潔：最後，完整的 API 將使開發人員能夠根據您公開的資料建立功能完整的應用程式。完整性通常會隨著時間的推移而發生，並且大多數 API 設計人員和開發人員會逐步建立在現有的 API 之上。這是每位擁有 API 的工程師或公司都必須努力實現的理想。
為了說明以下列出的概念，我將以照片分享應用程式為例。該應用程式允許使用者上傳照片，並以拍攝這些照片的位置以及描述與其相關的情緒的標籤來描述它們。
集合、資源及其 URL
了解資源和集合
資源是 REST 概念的基礎。資源是一個重要到可以本身被引用的物件。資源具有資料、與其他資源的關係，以及對其進行操作的方法，以便存取和操作相關資訊。 一組資源稱為集合。集合和資源的內容取決於您的組織和使用者需求。例如，如果您認為市場將受益於取得有關您產品使用者群的基本資訊，則您可以將其公開為集合或資源。 統一資源定位器 (URL) 可識別資源的線上位置。此 URL 指向您 API 資源所在的位置。基本 URL 是此位置的一致部分。 在照片分享應用程式的情況下，我們可以透過集合和資源公開有關使用該應用程式的使用者資料，並透過適當的 URL 存取。
- /users：使用者集合
- /users/username1：包含特定使用者資訊的資源
名詞更好地描述 URL
基本 URL 應整潔、優雅且簡單，以便使用您產品的開發人員可以輕鬆地在其 Web 應用程式中使用它們。冗長且難以閱讀的基本 URL 不僅不好看，而且在嘗試重新編碼時也容易出錯。始終應信任名詞。 沒有關於使資源名詞保持單數或複數的規則，儘管建議使集合保持複數。為了保持一致性，讓所有資源和集合分別具有相同的複數形式是良好的實踐。 保持這些名詞不言自明，有助於開發人員從 URL 中了解所描述的資源種類，這最終可以使他們在使用您的 API 時能夠自給自足。 回到照片分享應用程式，假設它有一個公共 API，具有 /users 和 /photos 作為集合。請注意，它們都是複數名詞嗎？它們也都不言自明，我們可以推斷 /users 和 /photos 分別提供有關產品的已註冊使用者群和已分享照片的資訊。
使用 HTTP 方法描述資源功能
所有資源都有一組可以對其進行操作的方法，以使用 API 公開的資料。 RESTful API 主要由 HTTP 方法組成，這些方法針對任何資源都具有明確且獨特的操作。以下是常用的 HTTP 方法列表，這些方法定義了 RESTful API 中任何資源或集合的 CRUD 操作。
| 方法 |
描述 |
| GET |
用於擷取資源的表示形式。 |
| POST |
用於建立新的資源和子資源 |
| PUT |
用於更新現有資源 |
| PATCH |
用於更新現有資源 |
| DELETE |
用於刪除現有資源 |
（如果您想知道 PUT 和 PATCH 之間的差異，請查看 StackOverflow 上的此訊息串。） 讓動詞離開 URL 也是一個好主意。GET、PUT、POST 和 DELETE 操作已經用於對 URL 描述的資源進行操作，因此在 URL 中使用動詞而不是名詞可能會使使用您的資源變得令人困惑。 在照片分享應用程式中，以 /users 和 /photos 作為端點，您的 API 的最終使用者可以輕鬆地使用上述 RESTful CRUD 操作來直觀地使用它們。
回應
提供回饋以協助開發人員成功
為開發人員提供有關他們如何使用您的產品的良好回饋，對於提高採用率和保留率大有幫助。 每個用戶端請求和伺服器端回應都是一個訊息，並且在理想的 RESTful 生態系統中，這些訊息必須是不言自明的。 良好的回饋包括對正確實作的正面驗證，以及對不正確實作的資訊性錯誤，這可以幫助使用者偵錯並更正他們使用產品的方式。對於 API 而言，錯誤是提供 API 使用環境的絕佳方式。 讓您的錯誤與標準 HTTP 程式碼保持一致。不正確的用戶端呼叫應與 400 類型的錯誤相關聯。如果存在任何伺服器端錯誤，則必須將適當的 500 回應與它們相關聯。針對您的資源使用的成功方法應傳回 200 類型的回應。 有很多回應程式碼。如需其他資訊，請查看此 REST API 教學課程。 一般而言，使用您的 API 時有三種可能的結果：-
- 用戶端應用程式行為錯誤（用戶端錯誤 - 4xx 回應程式碼）
- API 行為錯誤（伺服器錯誤 - 5xx 回應程式碼）
- 用戶端和 API 正常運作（成功 - 2xx 回應程式碼）
每當他們在使用您的 API 時遇到障礙時，協助您的最終使用者成功將有助於改善開發人員體驗並防止 API 濫用。詳細描述這些錯誤回應，但要保持簡潔和整潔。在錯誤程式碼中提供足夠的資訊，讓最終使用者開始解決問題的原因，如果您認為需要更多資訊，請提供其他文件的連結。
為您的所有 GET 回應提供範例
一個設計良好的 API 也會提供一個範例，說明針對 URL 成功呼叫時會得到的響應類型。這個響應範例應該簡單、清楚且容易理解。一個好的經驗法則是幫助開發人員在五秒內確切了解成功響應會提供什麼。 回到我們的照片分享應用程式，我們定義了 /users 和 /photos 網址。 /users 集合將以陣列形式提供所有已在應用程式註冊的使用者的使用者名稱和加入日期。 您可以使用 API 設計工具，以 Swagger (OpenAPI) 規範定義您的 API，如下所示：
- responses:
- 200:
- description: 成功傳回使用者資訊
- schema:
- type: array
- items:
- type: object
- properties:
- username:
- type: "string"
- example: "kesh92"
- created_time:
- type: "dateTime"
- example: "2010-01-12T05:23:19+0000"
請注意，每個響應項目中描述的資料類型和範例，終端使用者可以從成功的 GET 呼叫中獲得。終端使用者在 JSON 中收到的成功響應如下所示。
- {
- “data”:[
- {
- “Username”:“example_user1”,
- “created_time":“2013-12-23T05:51:14+0000 ”
- },
- {
- “username”:“example_user2”,
- “created_time":“2015-3-19T17:51:15+0000 ”
- }
- ….
- ]
- }
如果終端使用者使用 GET 方法成功呼叫端點，使用者應收到上述數據以及 200 響應代碼以驗證正確的使用方式。同樣地，不正確的呼叫應產生適當的 400 或 500 響應代碼，並附帶相關資訊以協助使用者更好地操作該集合。
請求
優雅地處理複雜性
您嘗試公開的數據可以通過許多屬性來描述，這些屬性對於使用您 API 的終端消費者來說可能是有益的。這些屬性描述了基本資源，並隔離了可以使用適當方法操作的特定資訊資產。 一個 API 應該力求完整，並提供所有必要的資訊、數據和資源，以幫助開發人員以無縫的方式與之整合。 但完整意味著要考慮 API 的常見用例。可能存在許多此類關係和屬性，為每個關係和屬性都定義資源並不是一個好的做法。 還應考慮資源公開的數據量。如果您嘗試公開大量數據，則可能會對伺服器產生負面影響，尤其是在負載和效能方面。 上述案例和關係是 API 設計中重要的考量因素，可以使用適當的參數來處理。您可以使用查詢參數中的 ‘?’ 後面的屬性掃描和限制響應，或者使用路徑參數隔離客戶端正在使用的數據的特定元件。 讓我們以我們的照片分享應用程式為例。 開發人員可以取得在特定位置和特定主題標籤中分享的所有照片的資訊，這可能會很有用。您還希望將每個 API 呼叫的結果數量限制為 10 個，以防止伺服器負載。如果終端使用者想要找到波士頓所有帶有主題標籤 #winter 的照片，則呼叫將為：
- GET /photos?location=boston&hashtag=winter&limit=10
請注意，複雜性現在如何簡化為與查詢參數的簡單關聯。如果您想根據客戶端的要求提供有關特定使用者的資訊，則呼叫將為：
- GET /users/kesh92
其中 kesh92 是 users 集合中特定使用者的使用者名稱，並將傳回 kesh92 的位置和加入日期。 這些只是您可以用來設計參數的一些方式，這些參數旨在實現 API 的完整性，並幫助您的終端開發人員直觀地使用您的 API。 最後，如果對某件事情有疑慮，就把它排除在外。如果您對特定資源或集合的功能有任何疑慮，那麼請將其留到下一個迭代。開發和維護 API 是一個持續的過程，等待正確使用者的回饋對於構建一個強大的 API 來說至關重要，該 API 使使用者能夠以創造性的方式整合和開發應用程式。
開始使用 API 設計
沒有一種適用於每個組織的 API 設計方法。上述建議僅僅是——建議和推薦，可以根據您的用例和需求使用或捨棄。 API 設計至關重要的主要原因之一是幫助終端消費者使用您的 API。他們的需求應是指引設計和建構出色 API 的明燈。
有興趣開始使用 REST API 的 API 設計嗎？ 了解 Swagger API 設計工具如何提供協助。