PUT vs PATCH — Full Replace vs Partial Update

PUT: Full Resource Replacement

PUT replaces the entire resource at the target URI with the request body. If the resource does not exist, PUT may create it. You must send all fields, even those that have not changed.

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

{
  "name": "Charlie Updated",
  "email": "charlie@example.com",
  "role": "admin",
  "bio": "DevOps engineer"
}

If you omit the bio field, it will be removed (set to null or default), because PUT replaces the entire resource.

PATCH: Partial Modification

PATCH applies partial modifications. Only include the fields you want to change:

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

{
  "role": "admin"
}

Only the role field is updated; all other fields remain unchanged.

Comparison Table

Aspect	PUT	PATCH
Payload	Complete resource	Only changed fields
Missing fields	Reset to defaults	Left unchanged
Idempotent	Yes	Not guaranteed
Creates resource	Yes (at known URI)	Typically no
RFC	RFC 9110	RFC 5789

When to Use Each

Use PUT when:

• The client has the complete updated resource
• You want deterministic, idempotent updates
• The resource can be fully reconstructed from the payload

Use PATCH when:

• You only need to change one or two fields
• Sending the full resource would be wasteful
• The resource is large or complex

JSON Merge Patch vs JSON Patch

PATCH has two common content types:

1. JSON Merge Patch (application/merge-patch+json) — Send a JSON object with only changed fields; null deletes a field
2. JSON Patch (application/json-patch+json) — Send an array of operations (add, remove, replace, move, copy, test)