如何閱讀 API 文件？

當您是 API 新手時，API 文件頁面可能看起來令人不知所措。但一旦您知道每個部分的含義，閱讀任何 API 就會變得容易得多。

下面我們將介紹如何理解 API 端點，如何從中構建請求，以及如何使用回應。

這是一個端點文件的範例：Get realtime weather。

大多數 REST API 文件都組織成相同的關鍵部分：

1. 基本資訊

1. 標題與描述

獲取即時天氣 (Get realtime weather)

即時天氣 API 方法允許使用者以 JSON 格式獲取最新的當前天氣資訊。

這告訴您：

端點做什麼 → 返回當前天氣

格式 → JSON

使用案例 → 獲取某個地點的最新可用資料

2. HTTP 方法

最常見的 HTTP 方法包括：

方法	含義	典型用法
GET	檢索資料	獲取天氣報告
POST	建立資料	建立使用者或提交表單
PUT	替換現有資料	更新完整資源
PATCH	部分更新	更新一個欄位
DELETE	移除	刪除一個項目

在我們的範例中，方法是 GET。

3. 端點 URL

範例：

http://api.weatherapi.com/v1/current.json

這是您將發送請求的 Base URL。

2. 請求

這描述了您發送到伺服器的請求部分。

1. 參數

大多數 GET 端點使用 查詢參數。
其他 API 也可能包括：

類型	出現位置	範例用途
Query Params	URL 中 `?` 之後	過濾、分頁
Path Params	URL 內部	`/user/{id}`
Headers	獨立部分	驗證 tokens
Body Params	請求 Body	POST 時發送的 JSON

在 WeatherAPI 的範例中，URL 中有三個查詢參數，出現在 '?' 之後並由 '&' 分隔。

http://api.weatherapi.com/v1/current.json?key=3432a351afd04b30bef75833252711&q=New%20York&aqi=no

名稱	必填	類型	用途
`key`	必填	string	API key
`q`	必填	string	地點
`aqi`	可選	string	包含空氣品質

如果 API 有更多參數，文件通常會允許擴展 URL：

?limit=20&offset=40&sort=created

2. 請求 Body（如果適用）

對於 GET 請求：通常 無 Body。
對於 POST/PUT/PATCH：Body 可以是：

JSON（最常見）

Form data

XML

Multipart（例如：檔案上傳）

範例 JSON Body（非來自 WeatherAPI）：

{
  "title": "Hello",
  "content": "This is a post"
}

3. 範例請求（有幫助但非強制）

範例幫助您驗證您發送的格式是否正確。

3. 回應

這部分描述伺服器返回給您的內容。

1. HTTP 代碼

當您查看 API 的回應部分時，首先看到的東西之一是 HTTP 狀態碼。

狀態碼告訴您請求是成功還是失敗。它們在幾乎所有 REST API 中都是通用的。

在 WeatherAPI 的回應規範中，主要的成功範例是：

🟢 200 OK

200 OK 意味著您的請求成功了。無論您是獲取天氣資料、使用者資訊還是產品列表——成功的讀取幾乎總是返回 200。

好的 API 文件還包括其他 HTTP 代碼：

狀態	含義
400	錯誤請求 (Bad request)
401	未授權 (Unauthorized)
404	未找到 (Not found)
500	伺服器錯誤 (Server error)

2. 回應規範

這是最重要的部分之一。

它解釋了：

您將收到什麼欄位

每個欄位的資料類型

它的含義

它是否是必填的

範例片段：

location (object)
  name: string (required)  — Name of the location
  region: string (required)
  country: string (required)
  lat: number (required)
  lon: number (required)

這告訴您：

回應包含一個頂級欄位 location

在它裡面是必填欄位，例如 name、lat、lon

您將使用此資訊來解析回應。

3. 範例回應（非常有用）

{
  "location": { ... },
  "current": { ... }
}

範例回應向您展示實際的形狀，並幫助您確認您的程式碼或 API 工具（如 Apidog）正在運作。

4. 關鍵重點

一旦您理解了這些核心部分——方法、URL、參數、請求 Body、狀態碼和回應結構——API 文件就不再那麼令人畏懼了。幾乎所有 REST API 都遵循相同的模式，因此您在這裡學到的技能適用於任何地方。

有了這個基礎，您可以自信地閱讀任何 API 文件，構建正確的請求，並解釋您收到的回應。從這裡開始，您可以在 Apidog 等工具中開始嘗試真實 API，並逐漸轉向更進階的概念，如驗證、分頁和錯誤處理。

您現在已經邁出了熟悉並高效使用 API 的第一大步。

現在您已經學習了如何閱讀 API 文件的基礎知識。讓我們用 章節總結 結束本章，然後深入探討 API 基礎知識。

如何閱讀 API 文件？

1. 基本資訊#

1. 標題與描述#

2. HTTP 方法#

3. 端點 URL#

2. 請求#

1. 參數#

2. 請求 Body（如果適用）#

3. 範例請求（有幫助但非強制）#

3. 回應#

1. HTTP 代碼#

2. 回應規範#

3. 範例回應（非常有用）#

4. 關鍵重點#