首頁 部落格 API 設計最佳實務...

API 設計最佳實務

Keshav Vasudevan
  2016 年 10 月 10 日

良好的 API 設計是團隊在努力完善其 API 策略時經常出現的主題。在先前的部落格文章中，我簡要討論了API 設計的重要性。良好設計的 API 的優點包括：改善開發人員體驗、加快文件編寫以及提高 API 的採用率。 但良好API 設計究竟包含哪些要素？在這篇部落格文章中，我將詳細說明設計 RESTful API 的一些最佳實務。

良好設計的 API 的特性

一般而言，有效的 API 設計將具有以下特性

    • 易於閱讀和使用：良好設計的 API 將易於使用，並且經常使用它的開發人員可以快速記住其資源和相關操作。
    • 難以誤用：實作和整合具有良好設計的 API 將是一個簡單的過程，並且編寫不正確的程式碼的可能性較低。它具有資訊豐富的回饋，並且不會對 API 的最終使用者強制執行嚴格的指南。
    • 完整且簡潔：最後，完整的 API 將使開發人員能夠根據您公開的資料建立完整的應用程式。完整性通常會隨著時間的推移而實現，而且大多數 API 設計人員和開發人員都會在現有的 API 上逐步建構。這是一個理想目標，每個擁有 API 的工程師或公司都必須努力實現。

為了說明以下列出的概念，我將以一個照片分享應用程式為例。該應用程式允許使用者上傳照片，並使用照片拍攝的地點和描述與之相關情感的主題標籤來描述它們。

集合、資源及其 URL

了解資源和集合

資源是 REST 概念的基礎。資源是一個本身值得參考的物件。資源具有資料、與其他資源的關係以及對其進行操作的方法，以允許存取和操作相關資訊。 一組資源稱為集合。集合和資源的內容取決於您的組織和消費者需求。例如，如果您認為市場將受益於取得有關您產品使用者群的基本資訊，則可以將其公開為集合或資源。 統一資源定位器 (URL) 可識別資源的線上位置。此 URL 指向您的 API 資源存在的位置。基本 URL 是此位置的固定部分。以照片分享應用程式為例，我們可以透過集合和資源公開有關使用該應用程式的使用者的資料，並透過適當的 URL 存取。

  1. /users：使用者集合
  2. /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 時有三種可能的結果：-

  1. 用戶端應用程式的行為錯誤（用戶端錯誤 - 4xx 回應程式碼）
  2. API 行為錯誤（伺服器錯誤 - 5xx 回應代碼）
  3. 用戶端和 API 運作正常（成功 - 2xx 回應代碼）    

當終端使用者在使用您的 API 時遇到阻礙時，引導他們走向成功，對於改善開發者體驗和防止 API 濫用將大有助益。清楚描述這些錯誤回應，但要保持簡潔明瞭。在錯誤代碼中提供足夠的資訊，讓終端使用者能夠開始著手修正問題，如果您認為需要更多資訊，請提供額外文件的連結。   

為您所有的 GET 回應提供範例

一個設計良好的 API 也會提供範例，說明在成功呼叫 URL 時可以預期的回應類型。這個範例回應應該簡單、清楚且容易理解。一個好的經驗法則是幫助開發人員在五秒內確切了解成功的回應會給他們什麼。 回到我們的照片分享應用程式，我們定義了 /users 和 /photos URL。/users 集合會以陣列形式提供所有在應用程式中註冊的用戶的用戶名和加入日期。 您可以使用API 設計工具，按照以下方式在 Swagger (OpenAPI) 規範中定義您的 API：

responses:
        200:
          description: Successfully returned information about users 
          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 資源嗎？訂閱 Swagger 電子報。每月收到包含我們最佳 API 文章、培訓、教學課程等內容的電子郵件。 訂閱

您可能也喜歡