[ADP-115] PATCH

概述

HTTP PATCH 方法用於對資源進行部分修改。與替換整個資源的 PUT 方法不同，PATCH 只更新特定屬性(property)或屬性。

請求格式

• 端點: 要更新的資源的 URL。
• HTTP 方法: PATCH
• 標頭:
  • Content-Type: 指定請求主體的媒體類型(例如 application/json-patch+json， application/merge-patch+json)。
  • Authorization: 如果需要，則包含認證令牌。
• 主體: 包含修改指令，根據指定的媒體類型進行結構化。

回應格式

成功回應

• 狀態碼:
  • 200 OK: 修改成功，回應包含更新後的資源。
  • 204 No Content: 修改成功，無回應主體。
• 標頭:
  • Content-Type: 指定回應主體的媒體類型(如果存在)。
• 主體: 如果狀態碼為 200 OK，則包含更新後的資源。

錯誤回應

錯誤回應應遵循 HTTP 問題詳情格式(RFC 9457)。回應應具有 Content-Type 為 application/problem+json 並包含以下屬性(property):

• type: 標識問題類型的 URI 引用。
• title: 問題類型的簡短、人類可讀摘要。
• status: HTTP 狀態碼。
• detail: 針對此問題發生的具體人類可讀解釋。
• instance: 標識問題具體發生的 URI 引用。

錯誤回應示例:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: zh-tw

{
  "type": "https://example.com/problems/invalid-patch",
  "title": "Bad Request",
  "status": 400,
  "detail": "補丁文件格式不正確或包含錯誤。"
}

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": "執行此操作需要身份驗證。"
}

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": "客戶端沒有修改此資源的權限。"
}

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": "要修改的資源不存在。"
}

HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Content-Language: zh-tw

{
  "type": "https://example.com/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "由於與資源當前狀態衝突,無法完成請求。"
}

指引

• 必須(MUST)在將補丁文件應用於資源之前對其進行驗證，以確保其格式正確且不包含錯誤。
• 應(SHOULD)使用標準化格式的補丁文件，如 JSON Patch (application/json-patch+json) 或 Merge Patch (application/merge-patch+json)。
  • 關於 JSON Patch 或 Merge Patch 的選擇請見 ADP-117。
• 必須(MUST)確保只有授權用戶才能執行 PATCH 操作，以維護安全性和數據完整性。
• 應(SHOULD)優雅地處理並發修改，可能使用諸如樂觀鎖定等機制。
• 必須(MUST)返回適當的 HTTP 狀態碼以指示 PATCH 操作的結果。
• 應(SHOULD)設計 PATCH 操作為冪等的，意味著多次應用相同的補丁不會導致不同的結果。
• 如果狀態碼為 200 OK，可以(MAY)在回應主體中包含更新後的資源。
• 針對陣列時，應(SHOULD)選擇使用 json-patch，而不是 merge-patch，因為 merge-patch 可能會覆蓋掉整個值。
• 可以針對集合(資源列表)做 PATCH 操作，例如 PATCH /users。

  TIP

  在使用 PATCH 方法更新集合中的某些單個資源時，標準並未明確規定應該返回什麼。然而，如果支持對集合進行 PATCH 操作，至少應該在 "add" 操作中返回新增的資源。 例如：

  PATCH /users
  [
    {
      "op": "add",
      "path": "/-",
      "value": {
        "firstName": "my first name",
        "lastName": "my last name"
      }
    },
    {
      "op": "remove", 
      "path": "/0"
    }
  ]

  在這種情況下，應該返回

  {
    users: [
      {
        id: "fake-id",
        "firstName": "my first name",
        "lastName": "my last name"
      }
    ]
  }

• 如果需要將值設置為 null，應該(SHOULD)選擇使用 json-patch，而不是 merge-patch，因為在 merge-patch 中，null 的含義是刪除該欄位。
• 使用 JSON-PATCH 時，如果任何操作失敗，則應根據 RFC-6902: 錯誤處理 停止補丁應用程序，並且不應修改任何內容。

示例

示例 1: JSON Patch

PATCH /users/123 HTTP/1.1
Host: example.com
Content-Type: application/json-patch+json
Authorization: Bearer token

[
  { "op": "replace", "path": "/email", "value": "newemail@example.com" },
  { "op": "add", "path": "/phone", "value": "+1234567890" }
]

示例 2: Merge Patch

PATCH /users/123 HTTP/1.1
Host: example.com
Content-Type: application/merge-patch+json
Authorization: Bearer token

{
  "email": "newemail@example.com",
  "phone": "+1234567890"
}

Accept-Patch 標頭

參閱 ADP-147。

Content-Type 標頭

參閱 ADP-117。

參考

• RFC 5789: PATCH Method of HTTP
• RFC 6902: JavaScript 對象表示法 (JSON) Patch
• RFC 7386: JSON Merge Patch
• JSON Patch vs JSON Merge Patch
• Update collection discussion

Changelog

• 2024/09/11 Add PATCH on collection rule.