PUT vs PATCH
Fast recall
Quick revision
Core answer
PUT sends the intended replacement state for a known target URI, while PATCH sends instructions for changing its current state. PUT is idempotent by method semantics; PATCH has no general idempotency guarantee.Interview-ready guide
Interview answer
PUT and PATCH can both update a resource, but their bodies mean different things. PUT carries the state that should exist at the target URI. PATCH carries a patch document that tells the server how to change the current state. The real difference is replacement state versus change instructions, not simply a large body versus a small one.
For PUT /profiles/42, a profile representation might contain the name, email, and notification setting that should now describe profile 42. If the target has no current representation, the server can create one there when the contract allows it. Sending the same representation again has the same intended effect, so PUT is idempotent. The API must document what a complete profile representation contains; HTTP does not say that every omitted database column automatically becomes null.
For PATCH /profiles/42, the body follows a patch media type. A JSON Merge Patch such as {"displayName":"Ada"} replaces that member and leaves unmentioned members unchanged; a null member normally requests removal. JSON Patch uses operations such as replace, remove, and add. Setting a value can be repeatable, while incrementing a counter or appending an item can apply the change twice. PATCH therefore has no method-wide idempotency guarantee.
Choose PUT when the client can describe the intended target state and replacement is the API contract. Choose PATCH when the client needs to send a defined set of changes. Either request can overwrite a newer edit, so If-Match with an ETag can make the update fail with 412 Precondition Failed when the client's version is stale. Both methods still need authorization and validation.
PUT vs PATCH
Direct Answer
The difference is that PUT sends the intended replacement state for a known target URI, while PATCH sends instructions for changing its current state. PUT is idempotent by method semantics; PATCH has no general idempotency guarantee.
Deep Dive & Architecture
PUT's idempotency comes from the HTTP meaning of the method, not from a Spring annotation. An endpoint that treats repeated PUT requests as “increment this value” breaks that meaning. The request representation describes the target state, but the API still decides which fields belong to that representation, which fields are server-managed, and whether a missing field is invalid or has a documented default.
PATCH leaves the change language to the patch media type. JSON Merge Patch treats object members as replacements and uses null to remove a member, which makes a stored JSON null difficult to express for that member. JSON Patch uses an ordered list of operations and paths. A server must apply a PATCH document atomically: it applies the complete change or none of it, rather than exposing a half-updated resource.
A conditional request solves another problem. If-Match says “apply this update only if the current ETag is one of these values.” It protects both PUT and PATCH from silently replacing work that another client saved after this client last read the resource.
Code Example
A replacement request sends the intended profile state:
PUT /profiles/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 64
If-Match: "profile-v12"
{"displayName":"Ada L.","email":"ada@example.com","alerts":true}
A partial-change request sends a patch document:
PATCH /profiles/42 HTTP/1.1
Host: api.example.com
Content-Type: application/merge-patch+json
Content-Length: 24
If-Match: "profile-v12"
{"displayName":"Ada L."}
Both requests are conditional on version 12. PUT supplies the intended profile state; PATCH supplies one change. A stale request fails instead of silently replacing a newer edit.
Check your understanding
Answer these without looking back at the article.
- Why is PATCH not inherently idempotent?
- What is the role of a patch media type?
- How does `If-Match` prevent a lost update?
Looking for a structured roadmap?
Every module on this page is also part of the full Java backend interview track.