When would you use PUT versus PATCH for an API update, and what contract details must be explicit for each?

PUT vs PATCH for resource updates

Compares replacement and partial-update semantics, including omitted fields, patch formats, validation, and concurrency.

1Say itAnswer out loud first

2CompareCompare with Core answer

3RefineRefine with Stronger and Advanced

TL;DR

PUT sends a representation intended to create or replace the state of the target resource, so it is naturally idempotent when the same representation is repeated. PATCH applies a partial modification described by a patch document. I use PUT when the client owns a complete replaceable representation and PATCH when partial updates are an explicit product need. Omitted replaceable fields in a PUT become absent or reset according to the resource contract; silently retaining them makes the endpoint behave like an ambiguous patch. The contract must also name the accepted patch media type.

Full answer below

Practice focus

PUT replacement semantics, PATCH documents, JSON Merge Patch, JSON Patch, null and omission, validation, authorization, and preconditions.

Answer first

Answer path

Core answer first, then checkpoints toward a stronger answer.

Start
Core answer
Start here. This is the direct spoken answer to practice first.
Why this question matters
Update endpoints become fragile when clients and servers disagree about what an omitted property means. PUT and PATCH can both update data, but they communicate different representation semantics.
PUT sends a representation intended to create or replace the state of the target resource, so it is naturally idempotent when the same representation is repeated. PATCH applies a partial modification described by a patch document. I use PUT when the client owns a complete replaceable representation and PATCH when partial updates are an explicit product need. Omitted replaceable fields in a PUT become absent or reset according to the resource contract; silently retaining them makes the endpoint behave like an ambiguous patch. The contract must also name the accepted patch media type.
Checkpoint
Stronger answer
Optional upgrade with examples, trade-offs, and sharper phrasing.
For PATCH I avoid inventing an ambiguous DTO where null sometimes means clear and sometimes means not supplied. JSON Merge Patch gives omission and null defined meanings, while JSON Patch describes operations against paths; each has authorization and validation implications. I validate the final resource state, not only individual changed fields, and I whitelist mutable properties so a patch cannot change ownership, tenant, or server-managed audit fields. PUT can create a known URI when the API deliberately supports that behavior, but many application APIs use it only for replacement.

Review signals

Use these to catch weak phrasing, shallow reasoning, and risky claims.

Common mistakesCandidateCommon mistakesMistakes that weaken the answer or signal shallow understanding.Open details

Details

Calling any DTO with optional properties a PATCH contract.
Treating omitted and null values as the same without documenting it.
Allowing patch paths to modify ownership or tenant fields.
Assuming every PATCH document is idempotent.

When would you use PUT versus PATCH for an API update, and what contract details must be explicit for each?

Practice focus

Answer path

Why this question matters

Review signals

Follow-up prompts

Continue the section

Tech stacks

Skill areas

Suggest an improvement