PATCH

Partial modification of a resource without replacing the full representation is the purpose of the HTTP PATCH method.

Table of Contents

Usage

A PATCH request sends a set of instructions describing how to modify an existing resource. Unlike PUT, which replaces the entire resource, PATCH changes only the specified fields or properties.

The request body contains a patch document in a format the server understands. The Content-Type header identifies the patch format. The Accept-Patch header in server responses advertises supported patch formats.

Note

PATCH is not deprecated. The method was standardized in 2010 and remains an active part of HTTP semantics. Confusion arises because PATCH was added later than other methods and some older frameworks lack native support.

Note

PATCH lacks idempotency guarantees. Applying the same patch twice may produce different results (e.g., appending to a list twice). Concurrent patches to the same resource risk conflicts without conditional requests (If-Unmodified-Since or If-Match).

Common patch formats

JSON Patch expresses modifications as an ordered array of operations: add, remove, replace, move, copy, and test.

Content-Type: application/json-patch+json

[
  {"op":"replace","path":"/email",
   "value":"alice@example.re"},
  {"op":"add","path":"/verified","value":true}
]

JSON Merge Patch uses a simpler approach. The patch document mirrors the target resource structure. Fields present in the patch overwrite existing values. Setting a field to null removes the field.

Content-Type: application/merge-patch+json

{"email":"alice@example.re","nickname":null}

Atomicity

The server applies all changes in a patch document as a single atomic operation. If any instruction fails, the entire patch is rejected and the resource remains unchanged.

Note

A PATCH request has side effects and is not guaranteed to be idempotent. Two identical patches applied in sequence to an "add to list" operation produce different results than a single application.

Properties

Property Value
Safe No
Idempotent No (not guaranteed)
Cacheable Conditional

Example

JSON Merge Patch

A client updates the email address of user 42 using JSON Merge Patch format. The server applies the change and returns 200 OK with the updated resource.

Request

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

{"email":"alice@example.re"}

Response

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

{"id":42,"name":"Alice","email":"alice@example.re"}

JSON Patch

A client applies two operations to a configuration resource: replacing the debug flag and adding a new logging level field. The server confirms with 204 No Content.

Request

PATCH /config/app HTTP/1.1
Host: api.example.re
Content-Type: application/json-patch+json
Content-Length: 102

[
  {"op":"replace","path":"/debug","value":false},
  {"op":"add","path":"/logLevel","value":"warn"}
]

Response

HTTP/1.1 204 No Content

Conditional patch

A conditional request using If-Unmodified-Since prevents modifying a resource already changed by another client. If the resource was modified after the given timestamp, the server returns 412 Precondition Failed.

Request

PATCH /docs/report.json HTTP/1.1
Host: api.example.re
Content-Type: application/merge-patch+json
If-Unmodified-Since: Mon, 01 Jan 2024 12:00:00 GMT
Content-Length: 21

{"status":"reviewed"}

Response

HTTP/1.1 412 Precondition Failed
Content-Length: 0

CORS

Cross-origin PATCH requests always trigger a CORS preflight. The browser sends an OPTIONS request first to confirm the server allows PATCH on the target resource.

PATCH vs PUT

PATCH sends only the changes, making requests smaller and more bandwidth-efficient for large resources. PUT sends the full representation every time, regardless of how many fields changed.

PUT is idempotent. Sending the same PUT request twice produces the same server state. PATCH is not guaranteed to be idempotent because operations like appending to a list produce different results on each application.

Use PATCH when updating specific fields on an existing resource. Use PUT when replacing the entire resource with a new representation.

PATCH vs POST

PATCH modifies an existing resource at a known URI. POST creates new resources or triggers server-side processing.

PATCH uses defined patch semantics such as JSON Patch and JSON Merge Patch. POST delegates semantics entirely to the server with no prescribed format for the request body.

See also

Last updated: April 4, 2026