PUT vs. PATCH in REST APIs

Teams often debate whether to differentiate between PUT and PATCH when designing APIs. If it’s a recurring question, it’s worth understanding properly.

PUT vs. PATCH

PUT

Full replacement of a resource.

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource…

PATCH

Partial update of one or more fields.

The PATCH method is similar to PUT except that the entity contains a list of differences between the original version of the resource identified by the Request-URI and the desired content of the resource after the PATCH action has been applied…

PATCH was introduced in HTTP/1.1. Full spec: https://tools.ietf.org/html/rfc2068

Example

PUT /users/:id
{
  "username": "",
  "nickname": "",
  "sex": "male",
  "age": 11,
  "address": "xxxx"
}

PATCH /users/:id/address
{
  "address": "xxxx"
}

Why bother distinguishing?

You could skip PATCH and use PUT for everything, but you’ll hit a few issues.

Updating the address only

Two options:

1. PUT /users/:id with the full payload. Downsides: unnecessary data transfer, and the consumer must construct the entire resource shape even for a minor update. The larger the resource, the worse it gets.
2. Add a dedicated endpoint like /users/:id/address that only accepts the fields you want to change. Switch the method to PATCH and the intent becomes clear: it’s a partial update.

Updating two fields (nickname and sex)

Continuing the previous pattern: PATCH /users/:id/address no longer fits. You might redefine it as:

PATCH /users/:id
{
  "nickname": "xxxx",
  "sex": "female"
}

That’s still reasonable.

Arbitrary fields

You can allow any combination of fields, but you must validate the input server-side. A naive implementation that blindly merges the request body into the entity opens security holes—think of fields that should never be updated, such as IDs. Add a whitelist or schema validation before applying changes.

Final Thoughts

PUT and PATCH are primarily about semantics. Modern tooling (axios, Spring, etc.) supports both, so choose the method that matches your scenario. Standards reflect lessons learned—follow them thoughtfully.

References

• RESTful API Best Practices
• REST Resource Naming Guide
• Using PATCH for partial updates
• HTTP/1.1 specification