# PUT vs PATCH

> Understand the difference between PUT and PATCH HTTP methods. Learn when to use full replacement vs partial update, and how each affects idempotency and API design.

Source: https://howhttpworks.com/compare/put-vs-patch
Last reviewed: 2026-10-04

> **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:

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

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

```json
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:

```http
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:

```http
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 | PATCH |
|---|---|---|
| Main meaning | Full replacement | Partial modification |
| Idempotent by spec | Yes | Not required |
| Retry safety | Usually straightforward | Depends on patch semantics |
| Common risk | Silent overwrites | Ambiguous change semantics |

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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT)
- [MDN Web Docs: PATCH](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH)
- [RFC 5789: PATCH Method for HTTP](https://www.rfc-editor.org/rfc/rfc5789)