回應 - API Academy

一旦您發送了 API 請求，下一步就是了解回應。回應告訴您請求是否成功，並且（如果成功）返回您請求的資料。

學習如何閱讀回應對於除錯、建構應用程式以及了解 API 行為至關重要。

在這篇文章中，我們將使用 Pet Store API 來解釋如何解釋回應結構、狀態碼和回應 Body。

1. 什麼是 API 回應？

一個 API 回應包含三個主要部分：

狀態碼

Headers

Body (通常是 JSON)

範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "pet_1Nv0FGQ9RKHgCVdK",
  "name": "Fluffy",
  "species": "DOG",
  "status": "AVAILABLE"
}

每個部分提供有關請求結果的不同資訊。

2. 狀態碼 — 首先要檢查的事

HTTP 狀態碼告訴您請求是否有效。

最重要且最常見的代碼是：

200 OK

這意味著：

您的請求成功

伺服器返回了預期的資料

您可以信任回應 Body

其他常見的狀態碼包含：

代碼	意義	何時發生
400 Bad Request	您的請求無效	缺少欄位、錯誤類型
401 Unauthorized	身分驗證失敗	缺少/無效 Token
404 Not Found	資源不存在	錯誤的 ID 或路徑
500 Server Error	伺服器端問題	與您的請求無關

閱讀 API 文件時，尋找：

您應該期望哪些狀態碼

API 是否針對不同代碼使用不同的 Body

3. 回應 Header (用於 Metadata)

Headers 描述回應本身，而非資料。常見 Headers 包括：

Content-Type: application/json → 告訴您格式

Date: → 伺服器時間戳記

RateLimit-Remaining: → 您還剩下多少請求額度

這些可能很有用，但對於初學者來說通常不如回應 Body 重要。

4. 回應 Body — 實際資料

大多數現代 API 將其回應 Body 當作 JSON 返回。
這是實際資料所在的位置。

來自取得寵物的範例回應 Body：

{
  "id": "pet_1Nv0FGQ9RKHgCVdK",
  "name": "Fluffy",
  "species": "DOG",
  "breed": "Golden Retriever",
  "ageMonths": 24,
  "status": "AVAILABLE",
  "photos": [
    "https://cdn.petstoreapi.com/pets/pet_1Nv0FGQ9RKHgCVdK/photo1.jpg"
  ]
}

要理解這個 Body，您應該將其與 API 的回應資料結構 (Response Schema) 進行比較。

5. 將回應 Body 與資料結構匹配

好的 API 文件定義了一個回應資料結構，描述了：

欄位名稱

類型 (string, number, object, array)

必填 / 可選

巢狀結構

範例 Pet Store 資料結構：

透過將回應與此表進行比較，您可以確認：

API 返回了所有必填欄位

類型匹配

資料結構正確

如果任何東西不匹配，您的應用程式可能會崩潰——這就是為什麼資料結構如此重要。

6. 範例：取得寵物

請求

GET /pets/pet_1Nv0FGQ9RKHgCVdK

成功回應

HTTP/1.1 200 OK

{
  "id": "pet_1Nv0FGQ9RKHgCVdK",
  "name": "Fluffy",
  "species": "DOG",
  "status": "AVAILABLE"
}

範例錯誤：找不到寵物

HTTP/1.1 404 Not Found

{
  "code": 1,
  "type": "error",
  "message": "Pet not found"
}

看到不同狀態碼有不同的回應結構是很常見的。
這就是為什麼 API 文件通常包含成功和錯誤範例。

7. 重點摘要

API 回應包含狀態碼、Headers 和 Body。

200 OK 是最重要的成功代碼。

回應 Body（通常為 JSON）包含您感興趣的實際資料。

使用回應資料結構來理解並驗證結構。

知道如何閱讀回應有助於您建構可靠的應用程式並快速排除問題。

現在您知道如何閱讀和理解 API 回應，您將能夠更自信地使用 API 資料，並在問題出現時進行故障排除。在下一節中，我們將介紹 OAS (OpenAPI 規格)——一個描述 API 的強大標準——它使探索、測試和記錄 API 變得更加容易。

回應

1. 什麼是 API 回應？#

2. 狀態碼 — 首先要檢查的事#

200 OK#

3. 回應 Header (用於 Metadata)#

4. 回應 Body — 實際資料#

5. 將回應 Body 與資料結構匹配#

6. 範例：取得寵物#

7. 重點摘要#