PATCH HTTP Method — Reference

What it does

PATCH applies a set of changes to a resource, rather than replacing it wholesale like PUT does. The request body describes a delta — which fields to change, and to what — and the server merges that delta into the existing resource. Everything not mentioned in the patch stays exactly as it was.

PATCH was added later than the other core methods (RFC 5789, 2010) specifically to fill this gap — before it existed, developers either abused PUT (forcing clients to always send the full resource, even for a one-field change) or invented their own partial-update conventions on top of POST.

Semantics

Property	Value	Why it matters
Safe	No	Changes state
Idempotent	Not guaranteed	Depends entirely on the patch format — a "set field X to 5" patch is idempotent; a "increment field X by 1" or "append to array" patch is not
Cacheable	No	Not a read
Request body	Yes	The delta, in whatever patch format the API defines
Response body	Optional	Often the updated resource

Syntax & example request

Merge-style PATCH (most common in practice, application/merge-patch+json):

PATCH /users/42 HTTP/1.1
Host: api.example.com
Content-Type: application/merge-patch+json

{"role": "admin"}

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "Sainesh", "role": "admin"}

JSON Patch style (RFC 6902, more explicit operations):

PATCH /users/42 HTTP/1.1
Content-Type: application/json-patch+json

[{"op": "replace", "path": "/role", "value": "admin"}]

curl example

curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"role": "admin"}'

Common status codes returned

200 OK — patch applied, updated resource returned → see 200
204 No Content — patch applied, nothing to return → see 204
409 Conflict — patch conflicts with the current resource state (common with If-Match-guarded PATCH) → see 409

PATCH vs PUT

	PATCH	PUT
Body describes	A delta / partial change	The entire resource
Idempotent	Not guaranteed	Yes, always
Fields not mentioned	Untouched	Erased (in a full replace)
Format	Defined by the API (merge patch, JSON Patch, custom)	Just the resource representation

If your PATCH format is a simple "here are the fields to overwrite" merge patch, it happens to behave idempotently — but the spec doesn't guarantee this for PATCH in general the way it does for PUT, precisely because some patch formats (increment, append, relative operations) genuinely aren't idempotent.

Real-world usage

Updating a subset of fields on a resource: PATCH /users/42 with just {"email": "[email protected]"}
JSON Patch (RFC 6902) for precise, ordered operations against nested structures
JSON Merge Patch (RFC 7396) for simple "shallow merge this object in" updates — the far more common style in REST APIs
GraphQL mutations conceptually fill a similar role, though outside the REST/PATCH world entirely

Security considerations

Because PATCH isn't guaranteed idempotent, the same retry-safety concerns as POST apply — a dropped connection followed by a naive retry can double-apply an "increment" or "append" style patch. If your patch format includes non-idempotent operations, pair PATCH with an idempotency key or If-Match/version check so retries are safe.

Partial updates also create a subtler risk: authorization checks written for "can this user modify this resource" sometimes forget to check per-field permissions, letting a PATCH sneak a change into a field the UI never exposed (e.g., a user PATCHing their own role field to admin if the API doesn't explicitly reject that field).

FAQ

Is PATCH idempotent?

Not guaranteed by the spec — unlike PUT. Whether a given PATCH endpoint is idempotent depends entirely on the patch format it uses. A merge-patch that sets absolute values is idempotent in practice; an operation-based patch that increments or appends is not.

What's the difference between JSON Patch and JSON Merge Patch?

JSON Patch (RFC 6902) is an ordered list of explicit operations (add, remove, replace, move, copy, test) against exact paths — precise but verbose. JSON Merge Patch (RFC 7396) is just a partial object that gets shallow-merged into the existing resource — simpler to write, but can't express operations like "remove this array element" cleanly.

Should I use PUT or PATCH for updating a single field?

PATCH — sending a full PUT payload just to change one field forces clients to first GET the current state (to avoid accidentally erasing other fields) and is wasteful. PATCH exists specifically for this case.

Fun fact

PATCH is the youngest of HTTP's "core nine" methods — standardized in 2010, thirteen years after HTTP/1.1 itself (1997) — because for over a decade, developers just lived with the PUT-requires-the-whole-resource limitation until it became painful enough to justify a new RFC.

PATCH