參數 - API Academy

在了解了方法與路徑之後，閱讀和使用 API 的下一步是了解參數。參數允許您自訂請求、篩選結果並向 API 提供輸入。

我們將繼續使用 Pet Store API 來說明不同類型的參數。

1. 什麼是參數？

參數是發送到 API 的資訊片段，用來告訴它您具體想要什麼。它們可以出現在請求的不同位置：

類型	出現位置	範例用途
路徑參數 (Path Parameters)	URL 路徑的一部分，通常在 `{}` 中	`/pets/{id}` 指定要取得哪隻寵物
查詢參數 (Query Parameters)	URL 中 `?` 之後	`/pets?status=AVAILABLE` 按狀態篩選寵物
Header 參數	HTTP 標頭 (Headers) 中	`Authorization: Bearer <token>` 用於身分驗證
Body 參數	請求 Body 中 (用於 POST/PUT/PATCH)	包含寵物詳細資訊的 JSON 物件

2. 路徑參數 (Path Parameters)

路徑參數是嵌入在 URL 路徑中的必要值。它們識別特定的資源。

範例：取得寵物

GET /pets/{id}

{id} 是路徑參數。將其替換為真實的寵物 ID：

GET https://api.petstoreapi.com/v1/pets/pet_1Nv0FGQ9RKHgCVdK

此請求取得 ID 為 pet_1Nv0FGQ9RKHgCVdK 的寵物。

3. 查詢參數 (Query Parameters)

查詢參數是新增到 URL 中 ? 之後的可選（有時是必要）值。多個查詢參數由 & 分隔。

範例：列出寵物

GET /pets?status=AVAILABLE

status=AVAILABLE 是查詢參數。

您可以新增多個參數：

/pets?status=AVAILABLE&species=DOG

查詢參數通常用於：

篩選結果 (status, category)

分頁 (limit, offset)

排序 (sort=asc)

4. Header 參數

Header 參數是在 HTTP 標頭內部發送的，而不是在 URL 中。它們通常攜帶：

Auth Tokens (Authorization)

內容類型 (Content-Type: application/json)

自訂 Metadata (X-Request-ID)

範例：

GET /pets/pet_1Nv0FGQ9RKHgCVdK
Headers:
  Authorization: Bearer <your-token>
  Accept: application/json

大多數 Header 由工具或框架自動處理，因此您通常不需要手動設定它們；但是，與 Auth 相關的 Header（如 Authorization）通常需要您自己新增。

5. Body 參數

Body 參數用於建立或更新資料的方法 (POST, PUT, PATCH)。它們通常是 JSON 格式，但也可能是 form data 或 XML。

範例：建立寵物

POST /pets
Body (JSON):
{
  "name": "Fluffy",
  "species": "DOG",
  "breed": "Golden Retriever",
  "ageMonths": 24,
  "status": "AVAILABLE"
}

Body 包含新資源的結構化資料。

API 規格定義了哪些欄位是必填的及其類型。

Body 通常是請求中最複雜的部分，因為它經常需要特定的、有時甚至是巢狀的結構。您需要仔細遵循 API 文件以正確建構它。

幸運的是，像 Apidog 這樣的工具可以幫助您輕鬆建立符合 API 要求的正確格式化 Body。

6. 實用提示

始終檢查規格中哪些參數是必填的。缺少必填參數通常會觸發 400 Bad Request。

可選參數可以增強您的請求（篩選、排序、分頁）。

對於包含空格或特殊字元的查詢參數，使用 URL 編碼。

像 Apidog 或 Postman 這樣的工具使您可以更輕鬆地在正確的位置新增參數並查看生成的請求 URL。

記住：路徑參數是必填的，查詢參數通常是可選的，而 Body 參數取決於 HTTP 方法。

7. 重點摘要

參數定義了您要求什麼資料或您正在發送什麼資料。

路徑參數識別特定資源。

查詢參數篩選、排序和分頁結果。

Header 參數傳遞 Metadata 或 Auth 資訊。

Body 參數攜帶用於 POST/PUT/PATCH 請求的結構化資料。

仔細閱讀 API 規格可確保您正確傳遞參數並獲得預期回應。

現在您對不同類型的參數以及如何使用它們有了紮實的理解，您準備好邁出下一步了。在下一節中，我們將更深入地探討請求 Body——探索如何為複雜的 API 操作建構資料，以及建立有效且合法請求 Payload 的最佳實務。

參數

1. 什麼是參數？#

2. 路徑參數 (Path Parameters)#

3. 查詢參數 (Query Parameters)#

4. Header 參數#

5. Body 參數#

6. 實用提示#

7. 重點摘要#

1. 什麼是參數？

2. 路徑參數 (Path Parameters)

3. 查詢參數 (Query Parameters)

4. Header 參數

5. Body 參數

6. 實用提示

7. 重點摘要