PATCH applies partial modifications to an existing resource. A consumer sends only the properties that change, rather than reconstructing the complete resource as with replacement-oriented PUT. section 4.3.1 section 5.3.4
Updating a product
Use PATCH /products/{productReference} with a modification model whose properties are optional. For example, changing a transaction’s review state can use {"checked": true}; a product update might send only a new price and description. The successful response returns the product’s new state. section 5.3.4 section 13.5.5
Choose PATCH when these trade-offs fit the operation:
- Prefer PATCH when transmitting or processing the complete resource would create meaningful cost at scale. section 13.5.5
- Restrict the modification schema to properties that are permitted to change; creation-only data such as a supplier may remain immutable. section 5.3.4
- Treat PUT and PATCH as interchangeable only at an early design stage; PUT may be simpler, while PATCH communicates partial modification more directly. section 4.3.4
- Avoid blindly replaying PATCH requests because identical replays are treated as non-idempotent and can jeopardize data integrity. section 12.5.2
Figure 4.8 Refer to this mapping when in doubt about choosing an HTTP method for an action. CRUD stands for create, read, update, delete.
Use the CRUD-to-HTTP mapping to distinguish PATCH’s update role from POST, GET, PUT, and DELETE. section 4.3.1
PATCH commonly uses JSON Merge Patch (RFC 7396), while JSON Patch (RFC 6902) is an alternative. Adding or removing PATCH operations affects compatibility: removal can produce 405 Method Not Allowed, whereas adding PUT alongside PATCH is backward compatible. section 5.3.4 section 15.2.4
