軟體應用程式在許多方面讓我們的生活變得更輕鬆和更好。我們幾乎每天都在使用它們，有些人發現自己使用應用程式的頻率比與其他人互動的頻率還要高。

但應用程式之間是如何互動的呢？其實，它們是透過 API（應用程式介面）來互動的。在這篇文章中，您將了解什麼是 API。我們將特別關注 Web API 及其設計和開發。

什麼是 Web API？

Web API 是一種設計用於網路上的 API。換句話說，基於網路的軟體應用程式、系統和服務使用 Web API 來在互聯網上交換資訊。它們發送請求並接收回應，通常以 JSON 或 XML 等格式呈現。

Web API 在現代軟體開發中扮演著關鍵角色，原因如下：

  1. 互操作性：API 是技術中立的，這意味著它們允許不同的軟體系統之間互相溝通，而不受技術堆疊的限制。這使得開發人員能夠無縫整合各種應用程式。

  2. 可擴展性：Web API 支援模組化開發，使應用程式的不同組件可以獨立構建、調試和擴展。這大大提高了系統的可擴展性。

  3. 靈活性和擴展性: 通過遵循標準做法和明确定義的規則，網頁 API 幫助應用程式擴展其功能。它們也足夠靈活，讓開發者能夠創造出 Dynamics 應用程式。

開發網頁 API 的方法

根據要求，網頁 API 可以使用各種方法開發。以下是一些常遵循的方法：

  • REST – 代表性状态转移 (REST) API 使用 HTTP 協定來執行操作。它們以无状态方式運行，意味著每個請求必須包括所有必要的信息，以便接收器處理和回應。

  • SOAP – 简单对象访问协议（SOAP）使用 XML 以结构化方式交换信息。

  • GraphQL – 用作querying 和 manipulating APIs。

  • gRPC – 使用HTTP/2 作為傳輸信息的遠程過程調用框架。

在即將到来的段落中，我們將探讨APIs 的設計和開發，著重於作為我們討論中心 protocol 的 REST APIs。

了解需求和目標

在任何軟件開發過程中，了解需求和目標是在開始之前至關重要。這有助於你計劃和估計项目和所需的成本、時間和其他資源。

當建立 RESTful APIs 时也是如此。你需要確定應用程序是否以無狀態方式交換信息，所涉 entities 是否可以表示為資源，以及服務是否足夠靈活以處理不同的數據格式。

定義資源和端點

REST APIs 围绕資源，表示系统中数据或对象的实体。每個資源都由唯一 URI 稱為 資源标识符 标识。這些資源可通过 端點 访问和操作，這是指定 URL，接收和處理客户端的請求。

最佳做法建議在端點中使用名詞作為資源，而不是用作表示資源操作的動詞。

請見以下例子的翻譯:

https://api.example.com/products

該端點遵循使用名詞作為資源(在這個例子中, products)的最佳實踐。請注意我如何使用了复數形式 – 產品? 如果您正在處理一堆物件,建議也使用复數。

然而,以下端點 https://api.example.com/add-product 不建議使用,因為它使用動詞並嘗試描述資源上的行為。這種方法對於更複雜的操作可能會變得複雜。

標準端點命名惯例的另一個重要方面是使用分层結構。這有助於清楚地表示資源之間的關係。

例如: https://api.example.com/categories/{categoryId}/products/{productId}。
在此,我們定義了一個端點,該端點在 category 和 product 資源之間保持了清晰的層次結構。

使用 HTTP 方法與狀態碼

在 REST API 中,HTTP 用作客戶端與服務器之間的通信。HTTP 有標準方法,主要用於在資源上執行操作。以下是這些方法及其用途的列表:

  • GET – 獲取資源的詳細信息。這些詳細信息由服務器在响应消息體中返回。

  • POST – 建立新的資源。要建立的資源詳細信息將傳送至請求消息體。

  • PUT – 根據其可用性，建立或更新資源。要建立或更新的資源詳細信息將傳送至請求消息體。

  • DELETE – 移除資源。

  • PATCH – 部分更新資源。要对資源所做的更改將傳送至請求消息體。

建議開發良好定義的REST API時，正確使用這些HTTP方法來進行對應的CRUD（建立、讀取、更新、刪除）操作。同時，您還應該確保API在响应消息體中返回適當的HTTP狀態代碼。

狀態代碼反映請求的結果。以下是您可以使用的常見HTTP狀態代碼的一些例子：

  • 200 OK

  • 201 Created

  • 204 No Content

  • 400 Bad Request

  • 401 未授权

  • 403 禁止

  • 404 找不到

  • 500 伺服器内部錯誤

  • 503 服務不可用

  • 504 閘道器逾時

使用正確的 HTTP 狀態代碼來準確表示 API 端點正在處理的請求結果。您也可以實作自訂的 HTTP 狀態代碼來描述應用程式的特定行為。

版本策略

隨著時間的推移，您開發的 API 將会发生演變，並進行更改。這時版本策略就變得非常重要。您必須確保已經在使用您 API 的客戶不會受到您所做的更改影響。

维持不同版本將使您的 API 向後兼容，並讓客戶能夠根據其需求使用偏好版本的 API。Postman 網站上這篇 有益的部落格 摘錄解釋了何時版本化您的 API 是理想的：

“您应在有需要讓用戶更改编寫的代碼才能繼續使用 API 時，為 API 進行版本控制。這種更改稱為「breaking change」，可能會影響 API 的輸入和輸出數據結構、成功和錯誤回饋，以及安全機制。

API 版本控制可以有不同方法。以下是一些方式：

  • URI 版本控制：在 URL 路徑中包含版本號。例如，https://api.example.com/v1/products。

  • 查詢參數版本控制：在 URL 中將版本號指定為查詢參數。例如，https://api.example.com/products?version=1。

  • HTTP 頭版本控制：在請求的 HTTP 頭中包含版本號。例如，使用自定頭如 X-API-Version: 1。

  • 內容协商: 在請求的 Accept 頭文件中指定版本，通常使用媒體類型。例如，Accept: application/vnd.example.v1+json。

  • 嵌入式版本控制: 在回應的媒體類型中嵌入版本號。例如，application/vnd.example.product-v1+json。

安全性考量

在開發 API 時考慮的另一重要方面是安全性。以下是一些要牢記的重要點：

  1. Implementation HTTPS to encrypt the information exchanged between the client and the server.

  2. Implement authentication and authorization to ensure that only users with the right privileges can perform operations on the resources. Common methods include Basic authentication, Bearer or Token authentication, JWT, and OAuth 2.0. Also, implement role-based access control to manage resource access.

  3. 實現輸入驗證和清理，以防止如SQL注入和跨站腳本攻击（XSS）的脆弱性攻擊。

  4. 實現速率限制和节流，以控制客戶端在特定時間內可以向服務器發送的請求數量。這有助於防止服務器過度負載。

文件化

API開發的一個關鍵但常被忽視的方面是文件化。記錄您的API對使用者了解其功能和應用至關重要。

文件必須 Comprehensive、容易理解，並遵循標準做法。包括請求和響應體的示例、所用HTTP狀態碼等。您可以遵循开放式API規範來描述您的RESTful API。

排序、過濾和分頁策略

你開發的 API 如果回傳太多記錄，可能會導致性能問題。提取大量數據然後進行排序或過濾 efficiency 较低。

為了解決這問題，應該 Enable 記錄的排序和過濾。你也應該實現分頁，將取回的記錄數量拆分，並設定限制以便利的導航和處理。

監控使用、記錄和健康状况

記錄 API 請求和响應對於除錯很有幫助。監控 API 使用能帮助你理解應用程序整體性能和行為。定期進行的健康檢查可以幫助你在有问题時采取必要的行動。所有這些步驟將使 API 更健壯、可靠。

結論

API，特別是 Web API，對於軟件應用程序在網路上進行通信是必不可少的。

這篇文章解釋了什麼是 Web API、為什麼它們重要以及開發它們的不同方法，著重於 REST API。你也學到了像定義資源和端點、使用標準 HTTP 方法與狀態代碼、版本策略、安全考慮、文檔等關鍵主題。

如果你覺得這篇文章有趣，不妨查看我在 freeCodeCamp 的其他文章，或是在 LinkedIn 上跟我聯繫。