PUT vs PATCH

TL;DR: Use PUT when the client means “replace this resource with exactly this representation.” Use PATCH when the client means “change only these parts.”

The Fastest Way To Decide

If your team is arguing about PUT versus PATCH, the real question is usually not “which update verb do APIs use?” It is:

• does the client know the whole desired final state
• or does it only know the fields it wants to change

If the client knows the whole resource and means to replace it, use PUT. If the client only wants to change part of the resource, use PATCH.

The Core Difference

PUT means “make the resource look exactly like this.”

PATCH means “apply these changes to the current resource.”

That sounds small, but it creates very different failure modes and retry behavior.

The Mental Model That Prevents Bugs

Imagine a user record with name, email, and role.

With PUT, the client sends the full record:

PUT /users/42
{
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin"
}

With PATCH, the client sends only the change it intends:

PATCH /users/42
{
  "email": "newalice@example.com"
}

If another field was added to the resource and the client does not know about it yet, PATCH is usually safer. PUT can accidentally wipe that field if the replacement semantics are strict.

PATCH Formats: Merge Patch vs JSON Patch

PATCH needs a documented patch format, signalled by Content-Type. Two are common.

JSON Merge Patch (RFC 7396, application/merge-patch+json) sends a partial document. null deletes a field, and arrays are replaced wholesale:

PATCH /users/42 HTTP/1.1
Content-Type: application/merge-patch+json
If-Match: "v7"

{"email": "newalice@example.com", "nickname": null}

JSON Patch (RFC 6902, application/json-patch+json) sends an ordered list of operations, which can address array elements and include a test precondition:

PATCH /users/42 HTTP/1.1
Content-Type: application/json-patch+json
If-Match: "v7"

[
  {"op": "test", "path": "/role", "value": "editor"},
  {"op": "replace", "path": "/email", "value": "newalice@example.com"},
  {"op": "add", "path": "/tags/-", "value": "beta"}
]

Servers advertise supported formats with Accept-Patch on OPTIONS responses and should return 415 Unsupported Media Type for others.

Concurrency: If-Match

Both methods suffer lost updates when two clients read, edit, and write. Send the ETag from your GET in If-Match; the server returns 412 Precondition Failed if the resource changed, and 428 Precondition Required if you require the header and it is missing (RFC 9110 section 13.1.1, RFC 6585).

Responses

A successful PUT or PATCH returns 200 OK with the updated representation, or 204 No Content with no body. A PUT that creates the resource returns 201 Created.

Idempotency And Retries

PUT is idempotent by definition (RFC 9110 section 9.3.4), so clients and proxies can retry it automatically after a timeout. PATCH is neither safe nor idempotent by definition (section 9.3.6).

PATCH can be safe to retry, but only if the operation itself is idempotent. “Set status to archived” is safe. “Increment balance by 1” is not.

When PUT Is The Better Choice

Use PUT when:

• the client owns the full representation
• replacement semantics are intentional
• retryability matters
• the resource lives at a known URL

Common examples:

• replacing a config document
• uploading a full file to a stable object path
• syncing a resource from a source of truth

When PATCH Is The Better Choice

Use PATCH when:

• the client only knows a subset of fields
• the resource is large and full replacement is wasteful
• you want to reduce accidental overwrites
• your UI edits one setting at a time

This is why PATCH is often the more natural choice for settings screens and profile editors.

Common Team Mistakes

Calling a partial update PUT because it feels simpler

That makes the contract misleading. The method says “replace,” but the server behaves like “merge.”

Calling everything PATCH without defining the patch format

PATCH is not self-explanatory unless your API documents whether it expects JSON Merge Patch, JSON Patch, or some custom semantics.

Falling back to POST for updates

POST works technically, but you lose useful protocol meaning and make retries harder to reason about.

FAQ

Is PATCH idempotent?

Not necessarily. PUT is idempotent by definition. PATCH can be idempotent if it sets a field to a value, but not if it applies additive operations like increment or append.

Should I use PUT or PATCH for a REST API update endpoint?

Use PATCH for most partial updates. Use PUT when clients really do send the full intended representation and the replacement semantics are part of the contract.

What happens if I PUT a resource with missing fields?

Under true PUT semantics, missing fields are treated as missing from the new representation, which often means they get cleared or removed.

What format does a PATCH request body use?

PATCH can use formats like JSON Merge Patch or JSON Patch. The important part is that the body describes a partial change, not a full replacement.

Can I use POST instead of PUT or PATCH?

You can, but you lose clarity. PUT and PATCH tell clients much more about replacement, partial updates, and retry behavior.

References

• MDN Web Docs: PUT
• MDN Web Docs: PATCH
• RFC 5789: PATCH Method for HTTP