Is the HTTP PATCH method idempotent? Explain what determines the answer and how you would make a PATCH endpoint safe to repeat.

## What the specs actually say PATCH was added by RFC 5789 for partial modification of a resource; RFC 9110 keeps its semantics unchanged. The spec states that PATCH is **neither safe nor idempotent**. That is a statement about the method as a whole — the guarantee that generic clients and intermediaries are entitled to rely on — and the reason is straightforward: unlike PUT, which carries a complete replacement representation, PATCH carries a *set of instructions*, and whether repeating instructions converges depends on the instructions. ## The three cases **Absolute assignment — idempotent.** JSON Merge Patch (RFC 7386) with `Content-Type: application/merge-patch+json` and body `{"status":"shipped"}` says "the status field is now this value". Apply it once, twice, ten times: the resource ends identical. Most CRUD-style PATCH endpoints fall here, which is why so many engineers wrongly believe PATCH is idempotent in general. **Relative or positional operations — not idempotent.** JSON Patch (RFC 6902), `Content-Type: application/json-patch+json`, is an operation list. `{"op":"add","path":"/tags/-","value":"vip"}` appends to the end of an array every time it is applied — two deliveries, two identical tags. `{"op":"remove","path":"/items/0"}` removes whatever is currently first, which is a different element on the second call, exactly like `DELETE /queue/head`. Any endpoint accepting `increment`, `append`, `push` or `adjust by delta` is non-idempotent by construction. **Conditional operations — idempotent by a different mechanism.** JSON Patch's `test` op (`{"op":"test","path":"/status","value":"pending"}` followed by the mutation) makes the whole patch fail with 409 if the precondition no longer holds. The second application fails instead of applying, so the state still converges. This is idempotency achieved by guarding rather than by the operation's own algebra. ## Why the method-level answer still matters A candidate who says "my PATCH endpoints are all merge-patch, so PATCH is idempotent" is making a category error. HTTP's method properties exist so that software that has never read your API documentation — connection pools, HTTP/2 client stacks, reverse proxies, service meshes — can decide whether to automatically retry a request whose response was lost. Those components look at the method only. Because PATCH is not declared idempotent, they will not auto-retry it, no matter how idempotent your particular handler is. Any retry of PATCH has to be a deliberate, application-aware decision. ## Making PATCH safe to repeat Three techniques, roughly in order of preference: **1. Design the patch format to be absolute.** If every operation you accept assigns a value rather than adjusts one, repetition is harmless by construction. This is the cheapest and most robust option and it is available for the large majority of real endpoints. If you need an "add a tag" operation, model it as set-semantics ("the tags are now exactly this set") or as its own resource (`PUT /orders/7/tags/vip`, which is idempotent because PUT is). **2. Gate with a precondition.** Send `If-Match: "<etag>"` with the ETag the client last saw. The first PATCH succeeds and the resource's ETag changes; a replay of the identical request now fails **412 Precondition Failed** instead of applying a second time. This converts an unsafe repeat into a clean, detectable no-op, and it simultaneously protects against lost updates from concurrent writers. Its limitation for retry purposes: a client that receives 412 cannot tell "my earlier attempt landed" from "someone else changed the resource", so it must re-read to decide. **3. Application-level deduplication.** For genuinely relative operations that cannot be reshaped — a balance adjustment, an inventory decrement — the only remaining option is for the server to recognize a repeated logical operation and not apply it twice. That is a separate contract layered on the endpoint, and it must be documented explicitly, because no generic client can infer it. ## What a strong answer sounds like "PATCH is not idempotent as a method — RFC 5789 says so — because the patch document decides. Merge-patch style assignments are idempotent; JSON Patch `add`-to-array, positional `remove`, and any increment are not. I make repeats safe by keeping the patch format absolute and by requiring `If-Match`, so a replay gets 412 rather than applying twice. And I don't rely on my endpoint's idempotency for transport-level retries, because middleware only sees the method."