When to Use PUT vs PATCH in REST APIs: Key Differences and Examples

Use PUT when you want to replace an entire resource with a new version, sending all fields. Use PATCH when you want to update only specific fields of a resource without affecting others.

Quick Comparison

This table summarizes the main differences between PUT and PATCH HTTP methods in REST APIs.

Factor	PUT	PATCH
Purpose	Replace entire resource	Update part of resource
Request Body	Full resource representation	Partial resource data
Idempotency	Idempotent (same request multiple times has same effect)	Not necessarily idempotent
Effect on Missing Fields	Missing fields are removed	Missing fields remain unchanged
Use Case	Complete update or create	Partial update
Typical Response	200 OK or 204 No Content	200 OK or 204 No Content

Key Differences

PUT replaces the entire resource at the specified URL. This means you must send all fields, even those that are unchanged. If you omit a field, it is usually removed or reset on the server. Because of this, PUT requests are idempotent: sending the same request multiple times results in the same resource state.

In contrast, PATCH applies partial modifications to a resource. You only send the fields you want to change, and the server updates those fields without touching others. This makes PATCH useful for small updates or when you don't have the full resource data. However, PATCH is not always idempotent, depending on how the server handles it.

Choosing between PUT and PATCH depends on whether you want to replace the whole resource or just update parts of it. Understanding these differences helps you design clear and efficient APIs.

Code Comparison

python

import requests

url = "https://api.example.com/users/123"

# PUT request to replace entire user resource
user_data = {
    "name": "Alice",
    "email": "[e-mail]",
    "age": 30
}

response = requests.put(url, json=user_data)
print(response.status_code)
print(response.json())

Output

200
{"id": 123, "name": "Alice", "email": "[e-mail]", "age": 30}

PATCH Equivalent

python

import requests

url = "https://api.example.com/users/123"

# PATCH request to update only the email field
partial_update = {
    "email": "[e-mail]"
}

response = requests.patch(url, json=partial_update)
print(response.status_code)
print(response.json())

Output

200
{"id": 123, "name": "Alice", "email": "[e-mail]", "age": 30}

When to Use Which

Choose PUT when:

• You want to replace the entire resource with a new version.
• You have all the data for the resource and want to ensure it is fully updated.
• You want your operation to be idempotent, so repeated requests have the same effect.

Choose PATCH when:

• You want to update only specific fields without sending the full resource.
• You want to minimize data sent over the network for small changes.
• You want to avoid accidentally removing fields by omission.

In summary, use PUT for full replacements and PATCH for partial updates.

Key Takeaways

Use PUT to replace an entire resource with complete data.

Use PATCH to update only specific fields without affecting others.

PUT requests are idempotent; PATCH may not be.

Omitting fields in PUT can remove them; in PATCH they stay unchanged.

Choose based on whether you want full replacement (PUT) or partial update (PATCH).