PUT vs PATCH

PUT sends the whole resource to replace it; PATCH sends only the change, and that makes repeating it riskier.

PUT replaces the whole resource with the representation sent, so a field the client leaves out is removed or reset. PATCH applies only the changes sent, so a field left out is untouched. That makes PUT idempotent by definition and PATCH idempotent only when its changes set values rather than add to them.

Take a user profile and a client that wants to change only the display name.

The same profile after a PUT and a PATCH that each send only the new name

PUT /users/7whole replacement

Sent: {"name":"Ana"}. The stored profile becomes exactly that. The email and language, missing from the body, are gone or reset to defaults.

PATCH /users/7partial change

Sent: {"name":"Ana"} as a JSON Merge Patch. The name changes; the email and language stay as they were.

PUT needs the whole resource. The client must read it first, change it, and send all of it back. That is simple to reason about, since the result is exactly what was sent, but it costs bandwidth and risks overwriting a change someone else made in between.

PATCH needs a patch format. JSON Merge Patch (RFC 7396) sends a partial document: fields present are set, a field set to null is removed. JSON Patch (RFC 6902) sends operations: {"op":"add","path":"/tags/-","value":"urgent"} appends to a list. Say in Content-Type which one is sent.

Where repetition differs. A merge patch that sets the name to "Ana" leaves the same profile however often it is sent. A JSON Patch that appends a tag adds it again each time. Because the method cannot tell which kind it carries, PATCH as a method is not idempotent, and clients do not retry it automatically.

The rule for choosing. Use PATCH for most edits, because clients rarely hold or should send the whole resource. Use PUT when the client genuinely owns the whole representation, such as a settings document or a file, and when creating at a URL the client chooses.

← → move through sections and cards