Both PUT and PATCH are used to update existing resources in web APIs, but they operate under completely different update semantics.

The replacement rule vs. The delta rule

  • HTTP PUT (Full Replacement): The payload in a PUT request is a complete representation of the resource. If an existing user has name, email, and bio, sending PUT with only {"name": "Jane"} will overwrite email and bio with null/empty defaults.
  • HTTP PATCH (Partial Update): The payload contains only the fields to be modified (a delta). Sending PATCH with {"name": "Jane"} leaves email and bio untouched.

Standard PATCH formats

  1. JSON Merge Patch (RFC 7396): Content-Type: application/merge-patch+json 
    {"email": "new_email@example.test"}
  2. JSON Patch (RFC 6902): Content-Type: application/json-patch+json 
    [{"op": "replace", "path": "/email", "value": "new_email@example.test"}]

How to test with curl

curl -i -X PATCH https://api.example.test/v1/users/usr_481 \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"status": "active"}'

Key takeaway

Use PUT when the client provides the complete, authoritative state of a resource. Use PATCH when applying surgical partial updates to specific attributes without overwriting omitted fields.