[ADP-319] 請求主體慣例

指南

• 不要(MUST NOT)在 GET 方法中使用請求主體
  • 在瀏覽器規範中，GET 請求不會有主體（負載）。參見 https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/send
• 可(MAY)在 POST、PUT 和 PATCH 方法中使用請求主體
• 當需要額外資訊時，可以(MAY)考慮在 DELETE 方法中使用請求主體
• 應(SHOULD)發送請求主體時，始終使用適當的 Content-Type 標頭

詳細說明

GET 方法

GET 請求旨在檢索資源，而不對伺服器造成副作用。因此，它們不應包含請求主體。相反，應使用查詢參數進行過濾、排序或分頁等操作。

正確用法示例:

GET /users?role=admin&status=active

錯誤用法示例:

GET /users HTTP/1.1
Content-Type: application/json

{
  "role": "admin"
}

POST 方法

POST 請求用於創建新資源或提交數據進行處理。它們應包含一個請求主體，其中包含要處理的數據或要創建的資源的詳細資訊。

示例:

POST /users
Content-Type: application/json

{
  "username": "johndoe",
  "email": "john@example.com",
  "role": "user"
}