When you design a write endpoint in an HTTP API, how do you choose between the PUT, PATCH and POST methods, and what does each one promise the client?

## The question each method answers A write method is part of the *contract*: it tells the client what will happen and what is safe to do twice. Picking one is not style — it changes what a retrying client, an SDK generator, and an on-call engineer may assume. ## POST — "process this representation" POST is the general-purpose method. The target URL is a *collection* or a *processing endpoint*, not the thing being created. The server decides the identity of what it makes and tells the client where it went: ``` POST /orders → 201 Created Location: /orders/42 ``` POST carries no idempotency promise. If the client times out and retries, it may create a second order. That is why platforms bolt an idempotency key onto POST — but that is an added protocol on top, not something POST gives you. ## PUT — "the resource at this URL is now exactly this" PUT targets the resource itself, and the body is a **complete representation**. The server's job is to make the stored state match the body. Two consequences follow directly: 1. **Idempotent.** Final state depends only on the request body, not on how many times it arrived. A client that times out can simply resend. 2. **Omission means removal.** If the stored order has `note: "gift"` and your PUT body has no `note`, the note is gone. This is the number-one source of production bugs when a UI form only knows about half the fields. PUT also means the *client* must know the URL beforehand. That is only possible when the client can produce or already knows the identifier — a natural key (`PUT /users/alice/settings`), or a client-generated UUID. ## PATCH — "apply this change document" PATCH exists because full replacement is expensive and dangerous when the client only wants to change one field. The crucial subtlety: the PATCH body is **not** a partial resource in the abstract — it is a document in a patch format, and the format is declared by `Content-Type`. The two standard ones are JSON Merge Patch (RFC 7386, `application/merge-patch+json`) and JSON Patch (RFC 6902, `application/json-patch+json`). Many real APIs instead accept plain `application/json` and define "present fields are updated, absent fields untouched" in prose; that works, but it is a house convention and it makes `null` ambiguous. PATCH is **not** idempotent by definition. A merge patch usually is (it sets absolute values); a JSON Patch with `add` to an array end, or a `test`-then-`copy` sequence, is not. Contracts that need retry-safety pin it down explicitly, often with a conditional request or an idempotency key. ## Choosing in practice - Creating something whose id the server assigns → **POST** to the collection, `201` + `Location`. - Creating or overwriting something at a client-known URL → **PUT** (this is the upsert case). - Changing one or two fields of a large resource, or a resource whose full representation the client cannot reconstruct → **PATCH**. - An operation that is not "set state" at all — cancel, refund, re-index → **POST** to an action endpoint; PUT/PATCH would lie about the semantics. ## What interviewers listen for They want to hear *why*: idempotency and "full representation vs diff". Candidates who only say "PUT updates, POST creates" miss that PUT can create, that PATCH needs a patch format, and that POST's lack of idempotency is the reason retry infrastructure exists.