[ADP-115] PATCH

Overview

The HTTP PATCH method is used to apply partial modifications to a resource. Unlike the PUT method, which replaces the entire resource, PATCH only updates specific fields or attributes.

Request Format

• Endpoint: The URL of the resource to be updated.
• HTTP Method: PATCH
• Headers:
  • Content-Type: Specifies the media type of the request body (e.g., application/json-patch+json, application/merge-patch+json).
  • Authorization: Authentication token if required.
• Body: Contains the instructions for the modifications, structured according to the specified media type.

Response Format

Successful Response

• Status Codes:
  • 200 OK: Successful modification, and the response contains the updated resource.
  • 204 No Content: Successful modification with no response body.
• Headers:
  • Content-Type: Specifies the media type of the response body (if present).
• Body: Contains the updated resource if the status code is 200 OK.

Error Response

Error responses should follow the HTTP Problem Details format (RFC 9457). The response should have a Content-Type of application/problem+json and include the following fields:

• type: A URI reference that identifies the problem type.
• title: A short, human-readable summary of the problem type.
• status: The HTTP status code.
• detail: A human-readable explanation specific to this occurrence of the problem.
• instance: A URI reference that identifies the specific occurrence of the problem.

Example error responses:

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

{
  "type": "https://example.com/problems/invalid-patch",
  "title": "Invalid Patch Document",
  "status": 400,
  "detail": "The patch document was not well-formed or contained errors."
}

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://example.com/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required to perform this operation."
}

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://example.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The client does not have permission to modify this resource."
}

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://example.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The resource to be modified does not exist."
}

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

{
  "type": "https://example.com/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The request could not be completed due to a conflict with the current state of the resource."
}

Guidance

• MUST validate the patch document before applying it to the resource to ensure it is well-formed and contains no errors.
• SHOULD use a standardized format for the patch document, such as JSON Patch (application/json-patch+json) or Merge Patch (application/merge-patch+json).
• MUST ensure that only authorized users can perform PATCH operations to maintain security and data integrity.
• SHOULD handle concurrent modifications gracefully, potentially using mechanisms such as optimistic locking.
• MUST return appropriate HTTP status codes to indicate the outcome of the PATCH operation.
• SHOULD design PATCH operations to be idempotent, meaning that applying the same patch multiple times does not result in different outcomes.
• It is possible to perform PATCH operations on collections (resource lists), such as PATCH /users.

  TIP

  When using the PATCH method to update some individual resources within a collection, the standard does not explicitly specify what should be returned. However, if support for PATCH operations on collections is provided, at least the newly added resources should be returned in the "add" operation. For example:

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

  In this case, the following should be returned:

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

• When dealing arrays, json-patch SHOULD be used instead of merge-patch, because merge-patch may overwrite the entire value.
• If you need to set a value to null, you SHOULD choose to use json-patch instead of merge-patch, because in merge-patch, null means deleting the field.
• MAY include the updated resource in the response body if the status code is 200 OK.
• When using JSON-PATCH, if any of the operations fail, the patch application SHOULD be stopped and nothing should be modified, as per RFC-6902: Error Handling.

Example

Example 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" }
]

Example 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 header

Please refer ADP-147.

Content-Type header

Please refer ADP-117.

References

• RFC 5789: PATCH Method of HTTP
• RFC 6902: JavaScript Object Notation (JSON) Patch
• RFC 7386: JSON Merge Patch
• JSON Patch vs JSON Merge Patch

Changelog

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