PUT vs PATCH

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.

Idempotency And Retries

PUT is easier to retry because sending the same complete representation again should land in the same final state.

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.