write
HTTP PATCH
Applies a partial modification to a resource, described by the patch document in the request body (e.g. JSON Patch or JSON Merge Patch). Only the specified fields change; the rest of the resource is untouched.
PATCH /path/{id} HTTP/1.1Properties
| Property | Value / Meaning |
|---|---|
| Safe | No - PATCH mutates server state. |
| Idempotent | Not guaranteed by the spec - it depends on the patch semantics (JSON Merge Patch is idempotent; a 'append' or 'increment' patch is not). |
| Cacheable | Only if the response explicitly sets caching headers - uncommon in practice. |
| Has body | Yes - the body is a patch document, not a full resource. |
| Body in response | Optional - often the updated resource or 204 No Content. |
Examples
curl -X PATCH -H 'Content-Type: application/merge-patch+json' -d '{"email":"[email protected]"}' https://api.example.com/users/42JSON Merge Patch: change only the email field.
curl -X PATCH -H 'Content-Type: application/json-patch+json' -d '[{"op":"replace","path":"/role","value":"admin"}]' https://api.example.com/users/42RFC 6902 JSON Patch operation list.
curl -X PATCH -H 'If-Match: "v3"' -d '{"status":"closed"}' https://api.example.com/tickets/9Partial update guarded by an ETag.
PATCH /users/42 HTTP/1.1\nHost: api.example.com\nContent-Type: application/merge-patch+json\n\n{"name":null}Merge Patch: null removes a field.
Gotcha
PATCH is not inherently idempotent - a patch like {"op":"add","path":"/tags/-","value":"new"} appends each time. Always advertise the patch media type (merge-patch+json vs json-patch+json); default application/json is ambiguous.
Related methods
HTTP PUT
Replaces the target resource entirely with the request payload, or creates it if it does not exist at the given URL. The client dictates the resource identifier, so PUT is idempotent.
HTTP POST
Submits an entity to the specified resource, often causing a change in state or side effect on the server. Used for creating resources, form submissions, and RPC-style calls.
HTTP DELETE
Removes the target resource, or requests its removal. Once deleted, subsequent requests typically return 404 or 410.
HTTP COPY
WebDAV extension (RFC 4918) that copies a resource from the Request-URI to the URI given in the Destination header. Can copy collections recursively based on the Depth header.
HTTP MOVE
WebDAV extension (RFC 4918) that moves a resource from the Request-URI to the Destination URI, equivalent to a COPY followed by a DELETE of the source. Preserves the resource across the rename or relocation.