API Style & Pattern Comparisons
Side-by-side trade-offs. Neither column wins — the consumer environment, the data shape and the operational budget decide.
PUT (replace) vs PATCH (partial update)
Send the whole resource and mean "make it exactly this" vs send only the changes and mean "modify these fields" — a difference in idempotency, payload and failure modes, not style.
The client naturally holds the full representation — an edit form that loaded the resource and now saves it.
Clients only know the fields they're changing — a full PUT forces a read-modify-write round trip first.
Naturally idempotent: replaying the same PUT converges on the same state; simple mental model.
A client built against an older schema PUTs the fields it knows — silently erasing every field added since.
Full payloads on every update; clients must stay current with the complete schema to avoid destructive writes.
Resources are large or contended and clients change one or two fields: toggling a flag, renaming, changing status.
The merge semantics are undefined — what null means, how arrays merge — so every client guesses differently.
Small payloads, no full read required, expresses intent field by field.
null-vs-absent is unspecified, so "clear this field" and "I didn't mention this field" collide in one representation.
A documented merge specification (JSON Merge Patch or your own rules) plus tests for the null/absent/array cases.
| Dimension | PUT (replace) | PATCH (partial update) |
|---|---|---|
| Idempotency | Yes by definition — same body, same result | Usually, but "append to array" style patches break it |
| Payload | Entire resource every time | Only the changed fields |
| Silent-erasure risk | High — omitted fields are removed | Low — omitted fields are untouched |
| null vs absent | Moot — everything is present | The core design decision; must be specified |
| Concurrency pairing | If-Match strongly advised — replaces blow away concurrent edits | Narrower writes collide less, but versioning still applies |