PATCH

The HTTP PATCH method applies partial modifications to a resource on the server.

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.

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 client sends an If-Unmodified-Since header to prevent 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

Takeaway

The HTTP PATCH method applies partial updates to a resource without replacing the full representation. JSON Patch and JSON Merge Patch are the two most common formats for describing changes. The operation is atomic but not idempotent, distinguishing PATCH from PUT.

See also

Last updated: March 6, 2026