PUT vs PATCH (and POST), and what does idempotency mean?

The methods

• PUT sends the complete representation of a resource to a known URI. The server replaces what is there. If the client omits a field, the server should clear it or set it to its default, because the request says “this is the resource now”.
• PATCH sends only the changes. The format matters: JSON Merge Patch (application/merge-patch+json, RFC 7396) sends a partial object, while JSON Patch (application/json-patch+json, RFC 6902) sends a list of operations such as add, remove, replace.
• POST creates a subordinate resource (the server assigns the id) or triggers a process such as “submit order”.

Idempotency

A method is idempotent if sending the same request N times leaves the server in the same state as sending it once. The response can differ (a second DELETE may return 404 instead of 204), but the effect on the server is the same.

Method	Safe (no state change)	Idempotent
GET, HEAD, OPTIONS	Yes	Yes
PUT	No	Yes
DELETE	No	Yes
POST	No	No
PATCH	No	Not guaranteed

PATCH can be idempotent ({"status": "closed"}) or not ({"op": "add", "path": "/items/-", ...} appends every time, as would “increment counter by 1”).

Why it matters

Networks fail. When a client times out, it does not know whether the request was processed. Idempotent requests can be retried safely by clients, load balancers and service meshes. Non-idempotent ones (paying, ordering) need protection, usually an Idempotency-Key header that the server stores so a retry returns the original result instead of charging twice.

How I test it

String body = "{\"name\":\"Ada\",\"email\":\"ada@example.com\",\"role\":\"admin\"}";

given().contentType(ContentType.JSON).body(body)
    .when().put("/users/42").then().statusCode(200);
given().contentType(ContentType.JSON).body(body)
    .when().put("/users/42").then().statusCode(200);

given().when().get("/users/42").then()
    .body("name", equalTo("Ada"))
    .body("role", equalTo("admin"));

Test ideas:

• Send the same PUT twice; the resource must be identical and no duplicate created.
• PUT without an optional field; check whether it is cleared (true PUT semantics) or kept (the API is really doing a PATCH, which should be documented).
• PATCH one field; verify every other field is unchanged.
• DELETE twice; the second must not error with 500 and must not delete something else.
• POST with the same Idempotency-Key twice; exactly one resource or charge should exist.

What interviewers look for

• A precise definition of idempotency in terms of server state, not response.
• Knowing PUT replaces while PATCH modifies, with the consequence for omitted fields.
• Linking idempotency to retries and how to make POST safe with idempotency keys.
• Concrete test cases that verify state after repeated calls.

Common mistakes

• Saying idempotent means “returns the same response every time”.
• Calling PUT “update” and PATCH “also update” without explaining omitted fields.