[ADP-114] DELETE

概述

HTTP DELETE 方法用於刪除指定的資源。當收到 DELETE 請求時，伺服器應該刪除由 URI 標識的資源，並返回一個指示操作結果的回應。

指導原則

• DELETE 方法必須(MUST)是冪等的。多個相同的 DELETE 請求必須與單個請求具有相同的效果。

• 可(MAY)在適當的情況下，實施軟刪除而不是硬刪除。這允許數據恢復並維護參照完整性。

  • 請參閱 軟刪除。

• DELETE 操作必須(MUST)要求適當的身份驗證，以防止未經授權的刪除。

• 實施適當的訪問控制，以確保用戶只能刪除他們有權限的資源。

• 回應

  • 成功刪除後，伺服器應該(SHOULD)返回 204 No Content 狀態碼。
  • DRAFT 如果您正在實施軟刪除，可以(MAY)考慮在回應主體中返回被刪除的資源或已刪除的資源。
  • 對於異步刪除，可(MAY)返回 202 Accepted 狀態碼。
  • 如果資源不存在，伺服器應該(SHOULD)返回 404 Not Found 狀態碼，並附帶問題詳情對象。
  • 如果用戶已通過身份驗證但未被授權刪除資源，伺服器應該(SHOULD)返回 403 Forbidden 狀態碼，並附帶問題詳情對象。

• 使用諸如 If-Match 或 If-Unmodified-Since 等標頭支持條件 DELETE 請求。參考條件請求。

• 所有錯誤回應必須(MUST)使用 RFC 9457 中定義的問題詳情格式。

• 根據 RFC 9110，DELELE 操作不可(SHOULD NOT)帶有請求主體(request body)。

• 如果要刪除的資源有關聯的子資源，應(SHOULD)在文件中明確說明此次刪除的範圍是否包括關聯資源。為了提高使用者體驗，可能(MAY)需要提供一個選項，讓使用者能夠自行決定是否要一併刪除關聯資源。這個選項的預設值應該是「否」，以避免不必要的資源刪除。

示例

• 成功刪除

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  
  HTTP/1.1 204 No Content

• 不存在的資源

  DELETE /v1/resources/999 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  
  HTTP/1.1 404 Not Found
  Content-Type: application/problem+json
  Content-Language: zh-tw
  
  {
    "type": "https://example.com/problems/not-found",
    "title": "Not found",
    "status": 404,
    "detail": "請求的 ID 為 999 的資源不存在。",
    "instance": "/v1/resources/999"
  }

• 未經授權的請求

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  
  HTTP/1.1 401 Unauthorized
  Content-Type: application/problem+json
  Content-Language: zh-tw
  
  {
    "type": "https://example.com/problems/unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "刪除此資源需要身份驗證。",
    "instance": "/v1/resources/123"
  }

• 禁止的請求

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  
  HTTP/1.1 403 Forbidden
  Content-Type: application/problem+json
  Content-Language: zh-tw
  
  {
    "type": "https://example.com/problems/forbidden",
    "title": "Forbidden",
    "status": 403,
    "detail": "您沒有刪除此資源的權限。",
    "instance": "/v1/resources/123"
  }

• 條件刪除

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  If-Match: "etag123"
  
  HTTP/1.1 204 No Content

• 接受處理

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  
  HTTP/1.1 202 Accepted

參考

• RFC 9110: DELETE
• MDN Web 文件: HTTP DELETE
• AIP-135
• 軟刪除真的必要嗎？]
• 刪除關聯資源討論