PUT vs PATCH

Simple explanation

Imagine you have a profile card on file at a gym. Two ways to update it:

• PUT is like handing the desk a *brand-new, fully filled-out card* and saying *"replace mine with this one."* Whatever was there before is gone; the card you handed over becomes the whole truth.
• PATCH is like passing a sticky note that says *"just change my phone number to 555-1234."* Everything else on the existing card stays exactly as it was.

Both update the resource, but PUT replaces the whole thing and PATCH changes only the parts you name.

Technical explanation

Both PUT and PATCH target an existing resource (e.g. /users/42), but they mean different things.

PUT carries a complete representation of the resource in its body. The server takes that body as the new state of the resource, replacing what was there. If you omit a field in a PUT body, you are effectively saying *"this field should now be absent (or reset to default)"* — not *"leave it alone."*

PATCH carries a patch document — a description of the changes to apply, not the whole resource. Only the fields you mention are touched; everything else is preserved. There are two standardized patch formats:

• JSON Merge Patch (RFC 7386) — the body looks like a sparse version of the resource. A key with a value updates that field; a key set to null deletes it; absent keys are left unchanged. Content-Type: application/merge-patch+json.
• JSON Patch (RFC 6902) — the body is an ordered array of operations (add, remove, replace, move, copy, test), each targeting a JSON Pointer path. Content-Type: application/json-patch+json.

Why it matters

Choosing the wrong method causes real bugs. Sending a partial object with PUT can silently wipe fields the client did not include, because PUT means *"this is the entire resource now."* Meanwhile, treating PATCH as if it were always idempotent can corrupt data when a request is retried after a timeout. Getting this right keeps your API predictable, safe to retry, and honest about what each call does.

How it works

Idempotency is the key distinction. A method is idempotent when making the same request N times leaves the server in the same final state as making it once.

• PUT is idempotent. PUT /users/42 with the same full body, sent once or ten times, results in the same stored resource every time. That makes it safe to retry after a network failure.
• PATCH is not guaranteed to be idempotent. It *can* be — e.g. a JSON Merge Patch that sets {"status": "active"} is idempotent. But it can also be non-idempotent, e.g. a JSON Patch operation like { "op": "add", "path": "/tags/-", "value": "vip" } appends "vip" to an array *every* time it runs, so ten retries add ten entries.

Status codes:

• 200 OK — the update succeeded and the response includes the updated resource in the body.
• 204 No Content — the update succeeded and there is no body to return.
• 201 Created — a PUT to a URL that did not exist yet *created* the resource there (an "upsert"). PATCH is generally not expected to create resources this way.

Real-world analogy

Think of editing a document. PUT is *"Select All → Delete → Paste my new version."* Whatever was there is replaced wholesale. PATCH is *"Find and Replace"* on a single line — you specify only the edit, and the rest of the document is untouched. If you accidentally "Paste" (PUT) a document that is missing three paragraphs, those paragraphs are gone. If you "Find and Replace" (PATCH), you never risk the parts you did not mention.

Important terminology

• Full representation — a complete copy of the resource's fields, the body PUT expects.
• Patch document — a description of changes (merge patch or operation list), the body PATCH expects.
• Idempotency — sending a request N times has the same effect as sending it once. PUT: yes. PATCH: not guaranteed.
• Upsert — an update that creates the resource if it does not already exist; PUT to a chosen URL can behave this way and return 201.