作為開發人員或技術人員，您可能聽說過“API”。聽到這個術語可能會讓您感到好奇。

本文將透過解釋可應用於 API 開發週期的基本概念和實踐來闡明 API。在開始使用 API 之前，您應該了解以下一件事 😂👇：

---

⭐️ 您會考慮在 GitHub 上給我們一顆星嗎？ ⭐️

---

您將從本文中學到什麼？

• 對 API、其關鍵概念及其在開發週期中的重要性的基本了解。

• API 的類型及其基礎知識。

• API開發的最佳實踐

• 您可以在其中試驗 API 的工具或平台。

介紹

API 是現代開發的基本組成部分之一。它們支援應用程式和資料之間的無縫互動。使用 API 無需手動提供應用程式和資料之間的通信，而是使開發人員可以輕鬆且有效率地進行這種互動。

無論您是建立 Web 應用程式、行動應用程式還是整合服務，API 對於允許應用程式中的不同元件與資料無縫連接都至關重要。

什麼是 API？

API（應用程式介面）是一個由一系列命令、函數和協定組成的框架，可實現不同應用程式之間的互動。其主要目的是定義開發人員可以用來與其軟體元件互動的方法和資料結構。

將 API 想像成餐廳的服務生；你告訴服務員（API）你想要什麼，他們把它帶到廚房（伺服器），然後將你的食物（資料）傳回給你。這就是它的工作原理！

API 可作為從應用程式取得請求、從伺服器取得必要資料，然後將處理後的資料傳回應用程式的連結。

API 類型

有針對不同用例和目的自訂的不同類型的 API。了解 API 類型有助於開發人員根據其特定需求選擇正確的 API。以下是最常見的 API 類型：

• 公共或開放 API ：這些 API 向任何開發人員公開提供，幾乎沒有任何限制，使開發人員能夠存取服務的資料和功能。

A good example of a place where you can get a public API is the [Some Random API platform](https://some-random-api.ml/). You will find a lot of API endpoints you can use freely in that service.

• 內部或私有 API ：它們的主要目的是團隊協作。它們通常不向外部開發人員開放，用於整合團隊或組織內的系統和服務。它們僅限於有權使用 API 的開發人員。

APIs are made private for many reasons. Some are made private to secure sensitive data, accelerate development for business reasons, or enhance internal workflows. If you're working on a large-scale application, it's best to protect your API by privatizing it.

• 合作夥伴 API ：這是私有 API 的範例；它們不對公眾開放。然而，它們是專門為外部合作夥伴使用而設計的。存取權限通常是透過合約協議授予的，允許合作夥伴整合和存取某些功能或資料。

現在您已經了解了 API 的主要類型，最好了解它們的應用方式和位置。不同類型的 API 有不同的用途，並且最適合某些特定的專案。

REST API

REST （表述性狀態傳輸）或RESTful API 是建立 Web 應用程式並與之互動的規則。它們依靠標準 HTTP 方法和協定來實現客戶端和伺服器之間的通訊。

REST API 設計簡單、可擴展且無狀態，這使得它們在 Web 和行動應用程式中很受歡迎。與典型的 API 不同，RESTful API 不是協定；而是協定。相反，他們利用它們進行互動。

當客戶端請求時，伺服器會回應請求的資料。就是這麼簡單！

REST API 原理

一些架構原則指導 RESTful API；他們獨特的架構構成了一切，確保它們保持高效且易於使用。以下是 REST API 的一些獨特原則：

• 無狀態性：從客戶端到伺服器的每個請求都必須包含瞭解和處理請求的所有必要資訊。伺服器不儲存有關客戶端的任何會話狀態。

This helps to simplify the server's architecture, as it doesn't need to manage and store session information, making the application more scalable. It also helps to give accurate information.

• 客戶端-伺服器架構：在 REST API 中，客戶端和伺服器是透過請求和回應進行互動的獨立元件。客戶端處理使用者介面和使用者體驗，而伺服器管理資料儲存。

• 統一介面：REST API 遵循一致的方式來存取資源。這包括使用GET 、 POST 、 PUT和DELETE等 HTTP 方法到 URI（統一資源辨識碼）來存取和操作資源。這使得 REST API 更容易理解和存取，因為開發人員可以依賴他們熟悉的模式。

• 可緩存性：這是大多數開發人員喜歡的 RESTful API 的原則之一。使用 REST API，來自伺服器的回應被標記為可快取或不可快取。快取可以減少客戶端與伺服器互動的次數並提高效能。

This increases efficiency by reducing unnecessary network calls, decreasing latency, and improving overall performance.

RESTful API 具有出色的結構，常用於現代開發週期。它的主要特點是它的原則，正是這些原則使得 REST API 成為現實。

圖片來源：菲爾·斯特金

SOAP API

SOAP （簡單物件存取協定）API 是一種用於在 Web 應用程式中交換結構化資訊的協定。與使用簡單 HTTP 方法的 REST 不同，SOAP 利用 XML 作為訊息格式並遵循更複雜的結構。

SOAP API嚴格用於Web應用程式，並且內建命令來確保訊息的安全性，使其適合安全性嚴格的應用程式。

REST 和 SOAP 之間的差異

如同上面的定義所示， REST和SOAP之間有明顯的差異。雖然兩者都用於網絡，但它們在架構、標準等方面仍然存在差異。

• 協定VS架構風格：

* **SOAP**: A protocol with standards and rules.

* **REST**: An architectural style that uses standard HTTP methods and protocols for interaction between web applications and data.

• 訊息格式：

* **SOAP**: Uses XML for message formatting.

* **REST**: Uses JSON but can also use XML, HTML, or plain text for message formatting.

• 複雜性：

* **SOAP**: It's more complex due to its standards and XML messaging.

* **REST**: Simpler and more flexible, easier to implement.

• 運輸：

* **SOAP**: Can use various protocols (HTTP, SMTP, etc.).

* **REST**: Typically uses HTTPS for communication.

透過了解該協定和架構風格之間的差異，開發人員可以根據自己特定應用的需求選擇合適的協定。

JSON 和 XML

JSON（JavaScript 物件表示法）和XML（可擴充標記語言）是標準的 API 通訊資料格式。這些格式具有相同的主要目的：對伺服器和客戶端之間的資料結構進行編碼，以便雙方都能理解。

JSON

JSON是一種源自 JavaScript 的輕量級資料交換格式。它易於人類閱讀和編寫，也易於機器解析和生成。

XML

XML是一種標記語言，它定義了以人類和機器可讀的格式對文件進行編碼的結構。 XML 主要以其處理複雜資料結構的能力而聞名。

JSON 和 XML 之間的差異

• 可讀性：

* **JSON**: Syntax is more readable, ideal for quick interaction, and more accessible for developers.

* **XML**: Comes with a more complex syntax. Best tailored for representing complex data structures and documents.

• 尺寸：

* **JSON**: More compact and lightweight. Results in faster data transmission and less bandwidth usage.

* **XML**: Larger due to extensive use of markdown tags.

• 資料類型：

* **JSON**: Supports data types such as strings, numbers, arrays, and objects.

* **XML**: All data is written in text, requiring parsing for specific data types.

• 解析和效能：

* **JSON**: Faster to parse, especially in JavaScript environments, due to compatibility.

* **XML**: Slower to parse and process, requiring more resources.

• 架構支援：

* **JSON**: JSON schema is available but not as extensive as XML schema.

* **XML**: XML schema is very powerful for verifying document structure and data types.

使用 API 時，您可以使用任何所需的資料格式進行通訊。最好了解其差異，因為在 API 開發中不存在可使用的「完美」資料格式。您可以根據您的需求選擇其中任何一個。

何時使用

有些情況下您可以使用 JSON 作為資料格式，有些情況下您可以使用 XML。知道何時何地使用它們非常重要。

您可以在以下情況下使用JSON ：

• 您需要一種輕量級的資料格式。

• 使用 Web API，尤其是在 JavaScript 環境中。

• 簡單性和可讀性至關重要。

• 您正在處理更簡單的資料結構，並且需要減少頻寬使用。

您可以在以下情況下使用XML ：

• 您想要處理複雜的資料結構。

• 需要驗證資料格式和結構。

• 使用需要大量元資料和描述性資料的應用程式。

• 資料交換需要具有高度可擴展性和自描述性。

透過了解同時使用 JSON 和 XML 的優點和案例，開發人員可以根據應用程式的需求決定使用哪種資料格式。

API端點

在本文中，您可能想知道 API 端點是什麼，因為您可能在本文中多次遇到術語「API 端點」。

API 端點是一個 URL，用戶端可以透過該 URL 存取 API 以執行檢索、更新或刪除資料等操作。端點代表 API 提供的功能和服務。

端點允許 API 與您正在處理的應用程式進行交互，從而實現通訊和資訊交換。它們可以透過 HTTP 方法存取，例如GET 、 POST 、 PUT和DELETE ，這些方法定義了將執行的操作類型。

API 端點範例

讓我們考慮一個用於在 Web 應用程式中管理學生資訊的 REST API 範例。 API 的基本 URL 可以是https://api.example.com 。現在，讓我們來看看其他端點和回應。

• 檢索學生列表：

* **Endpoint**: [https://api.example.com/students](https://api.example.com/students)

* **HTTP method**: GET

* **Purpose**: To retrieve a list of all registered students in the system.

* **Request**:

        GET https://api.example.com/students

    Here is the response you get:

        [
          {
            "id": 1,
            "name": "Opemipo Disu",
            "email": "[email protected]"
          },
          {
            "id": 2,
            "name": "Ralf Endrick",
            "email": "[email protected]"
          }
        ]

    In this example, we used the GET method to retrieve information from the system. After that, it gives us the data we requested from the endpoint in JSON format.

另一個例子可能是在系統中註冊學生的端點。讓我們建立它並查看它的響應。

• 新增新學生：

* **Endpoint**: [https://api.example.com/students](https://api.example.com/students)

* **HTTP Method**: POST

* **Purpose**: Adding a new student to the management system.

* **Request**:

        POST https://api.example.com/students
        Content-Type: application/json

        {
          "name": "Opemipo Disu",
          "email": "[email protected]"
        }

    **Response**:

        {
          "id": 1,
          "name": "Opemipo Disu",
          "email": "[email protected]"
        }

    In this case, you will notice we are working with the [https://api.example.com/students](https://api.example.com/students) endpoint, basically because we want to add a new student to the system; the only way the users could be accessed is by using that endpoint because it should have information related to the student in it.

現在，讓我們考慮刪除特定學生的資訊。我們可以這樣做：

• 刪除學生訊息

- **Endpoint**: [**https://api.example.com/students/{id}**](https://api.example.com/students/%7Bid%7D)

- **HTTP method**: DELETE

- **Purpose**: To delete a student by their ID.

- **Request**:

          DELETE https://api.example.com/students/1

     **Response**:

          {
            "message": "Student deleted successfully."
          }

When you want to delete a student's information using an API, addressing the specific data by its ID in the API endpoint ensures that you target the correct record.

透過了解端點的工作原理並查看一些範例，開發人員還可以使用 API 與 Web 應用程式互動並執行各種操作。

HTTP 方法

HTTP 方法定義對 API 端點辨識的資源執行的操作。我們有近 40 個已註冊的 HTTP 方法，但以下是四個最常見的方法：

• 得到

• 郵政

• 放

• 刪除

現在，我們將探討這些方法的用途，並為四種最常用的 HTTP 方法分別提供一個範例。

得到

GET方法從伺服器檢索資料，而不對伺服器資料進行任何更改。

前面在用於檢索學生資訊的端點中展示了其工作原理的範例。

再舉個例子：

要求：

GET https://api.example.com/students

回覆:

[
  {
    "id": 1,
    "name": "Opemipo Disu",
    "email": "[email protected]"
  },
  {
    "id": 2,
    "name": "Ralf Endrick",
    "email": "[email protected]"
  }
]

如上所示，GET 方法用於從端點檢索以 JSON 格式顯示的資料。

郵政

POST方法將資料傳送到伺服器以建立新資源。與用於檢索資料的 GET 不同，POST 向伺服器提交資料。 GET 依賴透過 POST 傳送到伺服器的資料。

前面已經解釋瞭如何使用 POST 方法的範例。學生的註冊範例就是一個可以使用 POST 方法的精確實例。

如果您錯過了，請再看一遍。

要求：

POST https://api.example.com/students
Content-Type: application/json

{
  "name": "Opemipo Disu",
  "email": "[email protected]"
}

我們使用 POST 方法發送請求。使用它是因為我們想將學生的資訊加入到伺服器。

這是我們這樣做得到的回應：

{
  "id": 1,
  "name": "Opemipo Disu",
  "email": "[email protected]"
}

在上面的回應中，POST 方法會自動幫助建立和註冊新學生。這就是 POST 方法的工作原理。

放

此方法用於使用新資料更新現有資源，或建立新資源（如果不存在）。它將資源的當前資訊替換為請求中提供的資料。

我們來看一個使用 PUT 方法更新學生資訊的範例。

要求：

PUT https://api.example.com/students/1
Content-Type: application/json

{
  "name": "Opemipo Hay",
  "email": "[email protected]"
}

回覆:

{
  "id": 1,
  "name": "Opemipo Hay",
  "email": "[email protected]"
}

在這種情況下，我們必須使用其 ID 來找到我們想要更新的資訊。我們使用 PUT 方法並加入了我們想要更新的資料。

刪除

此方法用於刪除現有資源。當發出 DELETE 請求時，伺服器會刪除 URI 標識的資源。

為此，我們以透過學生ID刪除學生資訊為例。

要求：

DELETE https://api.example.com/students/1

回覆:

{
  "message": "Student's information deleted successfully"
}

在請求中，我們使用 DELETE 方法根據使用者的 ID 刪除使用者的資訊。之後，我們收到回應：“學生資訊刪除成功。”

HTTP 狀態碼

HTTP 狀態碼是伺服器傳回的回應，用於指示客戶端請求的結果。它們透過向伺服器顯示客戶端請求的結果，在 API 通訊中發揮著至關重要的作用。

以下是許多 HTTP 狀態碼中的一些常見內容：

• 200

• 400

• 500

200（還可以）

當收到此回應時，說明請求成功，伺服器傳回請求的資料。

您可以獲得此回應的一個範例是當存在成功檢索資料的 GET 請求時。這在開發者控制台的網路標籤中表明操作已成功並且伺服器按預期處理了請求。

400（未找到）

當伺服器找不到所要求的資源或資料時，您會收到此回應。這可能是因為未正確取得資料或資源不存在。

當您對不存在的使用者使用GET請求時，可能會發生此錯誤。讓我們快速瀏覽一下：

要求：

GET https://api.example.com/users/583

回覆:

{
  "status": 404,
  "message": "Resource not found"
}

回應給出錯誤，因為假定端點中沒有資源。

500內部伺服器錯誤）

當您收到此回應時，伺服器遇到了意外情況，導致其無法滿足請求。

當處理請求時發生伺服器端錯誤時，您可能會收到此回應。

要求：

POST https://api.example.com/students
Content-Type: application/json

{
  "name": "Opemipo",
  "email": "[email protected]"
}

回覆:

{
  "status": 500,
  "message": "Internal server error"
}

500 內部伺服器錯誤表示一般伺服器端錯誤。它表明伺服器上出現了問題，不一定是由於客戶端的請求造成的。

雖然還有一些其他 HTTP 狀態程式碼，但您可以閱讀本文以了解有關它們的更多資訊。本文提供的是最常見的狀態程式碼。

認證與授權

雖然 API 安全至關重要，但身分驗證和授權是 API 安全的關鍵組成部分。 API 開發中的驗證是驗證使用者或應用程式身分的過程，通常透過 API 金鑰、OAuth 令牌或使用者憑證等技術。

另一方面，授權確定允許經過身份驗證的實體存取哪些資源或操作。

這些流程確保只有有效的使用者或應用程式才能存取 API 並根據其權限執行操作。

API 金鑰和 OAuth 的基本概念

API 金鑰是用於驗證與專案或應用程式關聯的請求的唯一辨識碼。

API 金鑰包含在 API 請求中，用於辨識呼叫專案或應用程式。它們通常用於追蹤和控制 API 的使用方式。 API 金鑰應保持安全，不得在程式碼中公開，以防止未經授權的存取。

但是，它們並不安全，應與其他安全措施（例如環境變數）一起使用。

另一方面， OAuth （開放授權）是一種基於令牌的身份驗證框架，允許第三方應用程式在不暴露使用者憑證的情況下存取使用者資料。

它被 Google 和 GitHub 等平台廣泛使用，以授予對用戶資料的有限存取權。它涉及使用者授權應用程式的流程，並且應用程式接收可用於發出授權 API 請求的存取權杖。與 API 金鑰相比，它提供了更靈活、更安全的方法。

API 安全的重要性

• 防止未經授權的存取：身份驗證可確保只有使用者和應用程式才能存取 API，從而防止未經授權存取敏感資料。

• 速率限制：身份驗證有助於追蹤 API 的使用情況，從而實現速率限制以防止資料濫用。

• 監控：身份驗證允許詳細記錄和監控 API 使用情況，這對於辨識錯誤至關重要。

速率限制和節流

API 使用速率限制來維持穩定和安全。這意味著它們限制使用者或應用程式在一定時間內可以發出的請求數量。這有助於防止伺服器過載。

它還確保應用程式中的所有使用者都能平等分配 API 資源。

為了管理速率限制，如果達到限制，應用程式應逐漸增加重試之間的等待時間。監控您的 API 使用情況以保持在這些限制之內。如果您儲存常用資料，則可以減少發出的請求數量。

使用頁碼和過濾器可以幫助您更快地管理大型資料集，從而減少 API 的負載。

測試 API

測試 API 在 API 開發過程中至關重要，以確保您的應用程式與伺服器正確通訊並按預期處理資料。專用工具可讓您在開發週期的早期發出 API 請求、檢查和分析回應並記錄問題。

讓我們探索一些用於測試 API 的最佳工具，並提供有關使用這些工具有效測試 API 的基本指南。

API測試工具

• Postman ： Postman是一個簡化API開發的工具。它允許您建立和發送請求、將 API 組織到集合中、自動化測試並產生詳細報告。

Ideal for both manual and automated testing, Postman supports various HTTP methods, making it flexible for testing.

• cURL ：此命令列技術支援使用 URL 進行資料傳輸。

cURL is used mainly because of its accessibility and flexibility, especially for developers comfortable with the command line.

• Swagger ： Swagger 提供了一套用於 API 文件和測試的工具。它允許您可視化 API 的資源並與之交互，而無需手動建立請求。

有關如何測試 API 的指南

1. 定義端點和方法

- Determine the API endpoint you wish to test and the HTTP method (GET, POST, PUT, DELETE) to use.

- Example: To fetch user data, you might use:

          GET https://api.example.com/users

2. 設定請求

- **Postman**: Open Postman, create a new request, enter the endpoint URL, and select the HTTP method. Add necessary headers like API keys and parameters.

    For a GET request to retrieve users, just set the URL to [**`https://api.example.com/users`**](https://api.example.com/users) and include any required headers or parameters.

3. 發送請求

- Click "**Send**" in Postman to execute the request and observe the response.

4. 分析回應

- **Status Code**: Indicates the success or failure of the request (e.g., 200 OK, 404 Not Found).

- **Headers**: Provide metadata about the response.

- **Body**: Contains the data returned by the API, typically in JSON or XML format.

- **Example**: A successful GET request might return a status code 200 and a JSON body with user data.

5. 處理錯誤

- If the request fails, analyze the status code and error message to diagnose the issue.

    - **Example**: A **404 status code** indicates that the endpoint is incorrect or the resource does not exist.

- Adjust the request accordingly and retry.

6. 自動化測試

- Postman supports scripting to automate tests. You can write pre-request scripts to set conditions and test scripts to validate responses.

    - **Example**: To verify a successful response, add the following script in Postman's "Tests" tab:

              pm.test("Status code is 200", function () {
                  pm.response.to.have.status(200);
              });

透過利用 Postman、cURL 和 Swagger 等工具，您可以簡化 API 測試流程，確保您的應用程式可靠且有效率地與外部服務互動。

結論

了解 API 對於任何剛起步的開發人員來說都是至關重要的。它們是現代開發的主要組成部分，可實現應用程式之間的無縫通訊和資料交換。

本文介紹了 API 的基本概念，包括它們的類型、REST 和 SOAP API 的關鍵原理、JSON 和 XML 等資料格式，以及 API 端點和 HTTP 方法的重要性。

此外，我們也透過身分驗證和授權探討了 API 安全性的各個方面，以及速率限制和限制的重要性。

如果您覺得這篇文章有幫助，請考慮在 GitHub 上給我們一顆星

⭐ 您可以考慮在 GitHub 上給我們一個 Star 嗎？

您的支持有助於我們繼續改進並向開發者社群提供有價值的內容。感謝您閱讀本文到目前為止！

---

原文出處：https://dev.to/latitude/understanding-apis-10-api-concepts-and-examples-23cn