HTTP PATCH Method: Partial Updates in REST APIs

What is the HTTP PATCH Method?

PATCH Request Format

RFC 5789 deliberately leaves the PATCH body format open — it does not mandate a specific representation. In practice, three formats have emerged as the most common.

1. Simple JSON Partial Object (Most Common)

Send a JSON object containing only the fields to update. The server applies these values to the existing resource, leaving all other fields untouched. This is by far the most widely used approach.

PATCH /api/v1/users/123 HTTP/1.1
Content-Type: application/json

{
  "email": "updated@example.com",
  "status": "inactive"
}

2. JSON Patch (RFC 6902)

JSON Patch (RFC 6902) defines a JSON document format for describing a sequence of operations to apply to a target JSON document. Each operation is an object with an op, a path, and optionally a value. Operations include: add, remove, replace, move, copy, test.

PATCH /api/v1/users/123 HTTP/1.1
Content-Type: application/json-patch+json

[
  { "op": "replace", "path": "/email", "value": "updated@example.com" },
  { "op": "replace", "path": "/status", "value": "inactive" },
  { "op": "add", "path": "/tags/-", "value": "verified" },
  { "op": "remove", "path": "/legacy_id" }
]

JSON Patch is powerful but verbose. It is best suited for APIs that need to describe complex document mutations, especially when clients need to atomically apply multiple operations.

3. JSON Merge Patch (RFC 7396)

JSON Merge Patch (RFC 7396) uses a simpler model: fields present in the patch body are updated, fields absent are unchanged, and fields explicitly set to null are deleted from the target resource.

PATCH /api/v1/users/123 HTTP/1.1
Content-Type: application/merge-patch+json

{
  "email": "updated@example.com",
  "legacy_id": null
}

Upsert Pattern with PATCH

What is an Upsert?

An upsert (update + insert) is an operation that creates a resource if it does not exist, or updates it if it does. Upserts are useful when clients are authoritative about a resource's identity and want to set its state regardless of whether it already exists.

PUT Upsert (Most Common)

PUT is naturally suited to upserts because it replaces or creates a resource at a specific URL. If the resource does not exist, the server creates it and returns 201 Created. If it exists, the server replaces it and returns 200 OK.

{
  "theme": "dark",
  "language": "en",
  "notifications": true
}

Conditional Headers for Upsert Control

Use conditional headers to control upsert behavior precisely:

• If-None-Match: * — only create; fail with 412 if resource already exists
• If-Match: "etag" — only update; fail with 412 if resource does not match ETag
• No conditional header — upsert (create or replace)

PUT /api/v1/settings/user-123-preferences HTTP/1.1
Content-Type: application/json
If-None-Match: *

{
  "theme": "dark",
  "language": "en",
  "notifications": true
}

PATCH Upsert

PATCH can also implement upsert behavior. This is less common because PATCH implies a partial update — and partial updates against a non-existent resource are ambiguous. However, some APIs support it for convenience when the client wants to initialize a resource with partial state.

{
  "theme": "dark"
}

PUT Upsert vs PATCH Upsert Comparison

Common PATCH Mistakes

Mistake 1: Sending the Full Object in a PATCH Body

PATCH should contain only the fields being changed. Sending the entire resource defeats the purpose and can introduce subtle bugs — for example, overwriting a field that another concurrent request just updated. If you want to replace the entire resource, use PUT instead.

PATCH /api/v1/users/123
{ "name": "John", "email": "john@example.com", "role": "admin", "status": "active" }

PATCH /api/v1/users/123
{ "email": "john@example.com" }

Mistake 2: Not Handling Partial Validation Correctly

PATCH validation must be contextual. Required field validators designed for POST or PUT will incorrectly reject PATCH requests that omit non-changed required fields. Your validation logic must distinguish between "field absent from PATCH body" (ignore) and "field explicitly sent as null" (potentially invalid).

Mistake 3: Wrong Content-Type Header

Always specify the correct Content-Type for your PATCH body format. Sending a JSON Patch document with Content-Type: application/json instead of application/json-patch+json can cause the server to misinterpret the body.

PATCH /api/v1/users/123 HTTP/1.1
Content-Type: application/json          <-- simple partial object
Content-Type: application/json-patch+json  <-- JSON Patch (RFC 6902)
Content-Type: application/merge-patch+json <-- JSON Merge Patch (RFC 7396)

Mistake 4: Unintentional Non-Idempotency

Be deliberate about whether your PATCH endpoint is idempotent. If clients may retry failed PATCH requests (common in unreliable network conditions), non-idempotent PATCH bodies — like increment operations — can corrupt data. Use absolute values in PATCH bodies when idempotency matters, or use If-Match headers to prevent duplicate application.

Related Topics