PUT vs PATCH: When to Use Each HTTP Method in APIs

The difference between PUT and PATCH comes down to one core idea: PUT replaces an entire resource, while PATCH updates only part of it. If you send a PUT request without including every field, the missing fields get wiped out. PATCH lets you send just the fields you want to change and leave everything else alone.

What PUT Actually Does

PUT is defined in RFC 9110 as a method that replaces the target resource with the request payload. Think of it like overwriting a file. Whatever you send in the body becomes the new state of the resource, completely.

Say you have a user record with three fields: name , email , and role . If you send a PUT request with only name and email , the server is supposed to treat role as absent and either set it to null or remove it entirely. That is the spec-compliant behavior.

PUT is also idempotent . Send the same PUT request ten times and the result is the same as sending it once. The resource ends up in exactly the state you described in the payload.

What PATCH Actually Does

PATCH was introduced later, in RFC 5789, specifically to handle partial updates. Instead of sending the full resource, you send only a description of the changes you want applied.

Using the same user record example: a PATCH request with just {"email": "new@example.com"} updates the email field and leaves name and role completely untouched. The server applies the diff, not a replacement.

Idempotency and Why It Matters

Idempotency is a property where running an operation multiple times produces the same result as running it once. It is a central concept in REST API design because networks are unreliable. Clients retry requests when they time out, and idempotent operations make retries safe.

Here is how the main HTTP methods stack up on safety and idempotency:

"Safe" in HTTP terms means the operation does not modify server state. GET and HEAD are safe. PUT, PATCH, POST, and DELETE are not. API safety and idempotency are separate concepts, and conflating them is a common source of confusion in REST API design.

PUT vs PATCH Side by Side

When to Use PUT and When to Use PATCH

Use PUT when:

• You are replacing a resource completely and you have all the data.
• You want guaranteed idempotent behavior, especially when the client is retrying after a timeout.
• You are creating or replacing a resource at a known URL (for example, PUT /users/42 to upsert a user with ID 42).
• Your resource is small and sending the full payload is not a bandwidth concern.

Use PATCH when:

• You only need to update one or two fields on a large resource.
• Sending the full resource every time would be wasteful or error-prone.
• You are building a form that lets users edit a single field, like changing a profile picture or toggling a setting.
• You want to minimize the risk of accidentally overwriting fields you did not intend to touch.

Real-World Request Examples

Here is a user object stored at GET /users/42 :

{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin"
}

PUT request (full replacement):

PUT /users/42 HTTP/1.1
Content-Type: application/json

{
  "id": 42,
  "name": "Alice",
  "email": "alice@newdomain.com",
  "role": "admin"
}

Result: the resource is replaced with exactly what you sent. All four fields are present, so nothing is lost.

PATCH request (partial update):

PATCH /users/42 HTTP/1.1
Content-Type: application/json

{
  "email": "alice@newdomain.com"
}

Result: only the email changes. name and role stay exactly as they were. This is the core value of partial updates in practice.

For more complex patching scenarios, the JSON Patch format (RFC 6902) gives you a structured way to express operations like "add", "remove", "replace", "move", and "test" in a single PATCH body. It is especially useful when you need atomic multi-field updates.

Common Mistakes with PUT and PATCH

• Treating PUT like PATCH. If your PUT handler only updates the fields present in the request body and silently ignores missing ones, you are implementing PATCH semantics under a PUT label. This confuses clients who rely on spec behavior.
• Assuming PATCH is always idempotent. If your PATCH handler appends to arrays or increments counters, retrying the request will produce different results. Document this clearly in your API.
• Sending a full resource body with PATCH. It works, but it defeats the purpose. Use PUT if you have the full resource.
• Forgetting to validate partial payloads. A PATCH request with an empty body or an unknown field should return a 400 Bad Request, not silently succeed.
• Using PUT to create resources at server-generated URLs. PUT implies the client knows the final URL. If the server assigns the ID, use POST to create and PUT or PATCH to update.

Test and debug PUT vs PATCH requests without writing a backend

Understanding the difference between PUT and PATCH is one thing. Seeing it live is another. Try our free tools to send, inspect, and compare HTTP requests so you can verify exactly how your API handles full replacements versus partial updates.

Try Our Free Tools →