方法與路徑

在學習 API 時，您首先需要了解的是 HTTP 方法和端點路徑。這兩者定義了您想要執行什麼動作以及針對哪個資源。

在本指南中，我們將使用流行的 Pet Store API（一個標準範例 API）來解釋這些概念。

1. HTTP 方法

HTTP 方法告訴伺服器您想要做什麼。最常見的方法有：

方法	意義	典型用途
GET	取得資料	取得寵物資訊
POST	建立資料	新增一隻新寵物
PUT	取代資料	更新現有寵物
PATCH	部分更新資料	更新特定欄位
DELETE	移除資料	刪除一隻寵物

範例： 如果您想查看有關寵物的資訊，您會使用 GET。如果您想新增一隻新寵物，您會使用 POST。

2. 端點路徑 (Endpoint Path)

端點路徑指定資源在伺服器上的位置。結合方法，它定義了完整的動作。

來自 Pet Store 的範例：取得寵物

GET /pets/{id}

GET = 取得資料

/pets/{id} = 指向特定寵物的路徑

{id} = 路徑參數，您將其替換為實際的寵物 ID

完整請求 URL 範例：

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

在這裡，pet_1Nv0FGQ9RKHgCVdK 是您要查詢的寵物 ID。

關於路徑的原則

以下是 REST API 中關於端點路徑的一些基本原則：

基於資源 (Resource-Based)：路徑應該代表資源（名詞），而不是動作（動詞）。例如，使用 /users 而不是 /getUsers。

階層結構：路徑可以顯示關係。例如，/users/1234/orders 表示使用者 1234 的所有訂單。

使用路徑參數：像 {petId} 這樣的路徑參數允許您引用特定資源。

複數 vs 單數：對集合使用複數名詞（/pets 表示所有寵物），對特定項目使用單數（通常隱含在 ID 前，但路徑本身通常是複數形式，如 /pets/12345）。

清晰與一致性：保持端點路徑簡單、直觀且在整個 API 中保持一致。

透過遵循這些 RESTful 路徑慣例，API 變得更容易理解、使用和維護。

3. 方法與路徑如何協同工作

讓我們在實作中結合方法與路徑：

動作	方法	路徑	描述
取得寵物	GET	/pets/{id}	取得有關特定寵物的資訊
建立寵物	POST	/pets	使用提供的資料建立一隻新寵物
更新寵物	PUT	/pets/{id}	取代現有的寵物記錄
刪除寵物	DELETE	/pets/{id}	移除特定寵物
列出寵物	GET	/pets	取得寵物列表

請注意，相同的路徑可以用於不同的方法來執行不同的動作。例如：

GET /pets/pet_1Nv0FGQ9RKHgCVdK   → 取得寵物資訊
DELETE /pets/pet_1Nv0FGQ9RKHgCVdK → 移除寵物

4. 給初學者的實用提示

在建構請求之前始終檢查方法 —— GET 通常不接受 Body，而 POST 和 PUT 通常需要一個。

理解路徑參數：任何在 {} 中的內容都必須替換為實際值。

某些 API 允許在路徑後使用可選查詢參數（例如 /pets?status=AVAILABLE）。

使用像 Apidog 這樣的工具可以輕鬆地視覺化方法 + 路徑並查看即時回應。

5. 重點摘要

理解方法與路徑是使用 API 的基礎：

方法告訴伺服器您想做什麼 (GET, POST, PUT, DELETE, PATCH)。

路徑告訴伺服器您正在對哪個資源進行操作。

結合方法與路徑定義了 API 中的唯一動作。

使用像 Pet Store 這樣的範例進行練習有助於您快速掌握這些概念。

一旦您對方法與路徑感到自在，您就可以繼續學習參數，這是 API 拼圖的下一塊。

1. HTTP 方法#

2. 端點路徑 (Endpoint Path)#

關於路徑的原則#

3. 方法與路徑如何協同工作#