HTTPRESTAPI Designjunior level

PUT vs. PATCH in HTTP APIs

the question

What is the difference between `PUT` and `PATCH`, and when would you use each one in an HTTP API?

what they're testing: The interviewer is probing whether you can turn HTTP method semantics into a predictable update contract for API clients.

a strong answer

PUT replaces or creates the state of the resource at the request URI with the state represented by the request body. PATCH applies a set of changes to that resource. Use PUT when the body defines the resource's replacement state. Use PATCH when the body is a patch document describing changes.

A PATCH body is not automatically "the fields to update." Its media type defines how to interpret it. JSON Merge Patch uses a JSON value as a merge template: object members update or add values, and null removes existing members. JSON Patch uses an ordered array of operations such as replace and remove. The API should document supported patch media types, require the matching Content-Type, and can advertise them with Accept-Patch.

PUT is idempotent by HTTP semantics, so retries have the same intended effect as one request. PATCH is not idempotent by definition, although a particular patch can be. Replacing an email with a fixed value may be idempotent; appending an array item may not be. To avoid lost updates, return a strong ETag, require the client to send it in If-Match, and reject a mismatch with 412 Precondition Failed.

Where people slip

the tempting wrong answer, and what's actually true

PATCH is just PUT with a smaller request body.
Body size is not the distinction. PUT defines replacement state for the target resource, while PATCH carries a patch document that describes changes.
PATCH requests are always non-idempotent.
PATCH is not idempotent by definition, but a particular patch can be idempotent, such as replacing a field with a fixed value.
PUT can only update a resource that already exists.
PUT can create the target resource when it has no current representation, provided the server allows PUT at that URI.
A partial JSON object is automatically a valid PATCH document.
PATCH has no default document format. The body must follow a patch media type and the contract accepted by the server.

If they push further

Can PATCH be idempotent?

Yes. Replacing a field with a fixed value can be idempotent, while an operation such as appending to an array may produce another change on every retry.

How would you prevent lost updates when two clients edit the same resource?

Return a strong `ETag` with the representation and require `If-Match` on the update. Reject a mismatched tag with `412 Precondition Failed`.

What is the difference between JSON Patch and JSON Merge Patch?

JSON Patch is an ordered array of operations and paths. JSON Merge Patch uses a JSON value as a merge template; in an object patch, `null` removes an existing member.

Sources

Now answer it yourself.

Reading a strong answer is easy. Producing one under pressure is the skill the interview tests. Gapmap grades your answer against the same bar an interviewer would.

was this useful?

beta

The interviewer part is in the works.

The diagnostic, personal maps, and AI mock interviews are being finished right now. The notes stay free either way. Leave an email and you'll get the first-cohort invite, plus a month of Pro when it opens.