[ADP-117] PATCH Request Content-Type

review phase 1

Refactor with ADP-115

When implementing PATCH requests in your API, it's crucial to choose the appropriate content type. This document provides guidelines for selecting between JSON Patch (application/json-patch+json) and JSON Merge Patch (application/merge-patch+json).

JSON Patch (application/json-patch+json)

Use Cases

• Complex, multi-step operations on JSON documents
• Fine-grained control over specific parts of a JSON structure
• Diverse operation types (add, remove, replace, move, copy, test)

Example

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

Guidance

• MUST set Content-Type: application/json-patch+json in the request header
• MUST validate the patch document structure and operations
• SHOULD use for complex updates requiring multiple operations
• MUST ensure atomicity of patch operations (all succeed or all fail)
• SHOULD document supported JSON Patch operations clearly

JSON Merge Patch (application/merge-patch+json)

Use Cases

• Simple partial updates to JSON documents
• Straightforward field value replacements
• Low-complexity operations not involving arrays or nested objects

Example

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

Guidance

• MUST set Content-Type: application/merge-patch+json in the request header
• MUST validate the merge patch document format
• SHOULD use for simple updates not requiring multiple operations
• SHOULD NOT use when fine-grained control or diverse operations are needed
• SHOULD clearly document Merge Patch usage and limitations

Choosing Between JSON Patch and Merge Patch

Aspect	JSON Patch	JSON Merge Patch
Complexity	High	Low
Control	Fine-grained	Coarse-grained
Operation Types	Multiple	Primarily replace
Document Structure	Can modify structure	Maintains structure
Use Case	Complex updates	Simple updates

Best Practices

• Analyze your API's update requirements before choosing a patch format
• Document the chosen patch format clearly in your API specifications
• Implement proper error handling for invalid patch documents
• Consider offering both patch formats if your API has diverse update scenarios
• Ensure your API consumers understand the implications of each patch format