PUT vs PATCH — what's the difference, and why the name vanished after an avatar change

A user changes their avatar. You send the new picture URL to the server: { "avatar": "cat.png" }. The avatar updates. And the name and email in the profile — are gone.

The server isn't broken. It did exactly what you asked. You sent the request with PUT, and PUT means “here's the new version of the profile, whole.” The new version had only the avatar field. So the other fields don't exist anymore.

You needed PATCH. Let's see how they differ and when to use which.

In short: what each one does

PUT — “replace it whole.” You send the full version of the object, and it takes the place of the old one. Whatever isn't in the request isn't in the result. Like replacing an old chest of drawers with a new one: the old drawers don't move over.

PATCH — “fix this part.” You send only what changes. The server leaves everything else alone. Like repairing one drawer in the same chest.

Both methods are part of a REST API, and both change existing data. The difference is what “missing” means in the request body.

Point by point

• What you send. PUT — the whole object, all fields. PATCH — only the changed fields.
• What's missing from the body. PUT — the field is erased or reset to its default. PATCH — the field stays as it was.
• Repeating the same request. PUT is idempotent by the standard: send it ten times and the result is the same as once. PATCH — not necessarily. A request “add a tag to the list” sent twice adds two tags.
• If the object doesn't exist yet. PUT may create it by the standard — the server replies 201 Created. PATCH usually replies 404. More on codes in our breakdown of HTTP status codes.
• Request size. PUT is heavier: you send everything, even what didn't change. PATCH sends the minimum.
• Risk of overwriting someone else. Higher with PUT. Two people opened the same profile. One changed the name, the other the phone. Both sent a full PUT. The second request silently brings back the old name. With PATCH, each edits their own field.

Hidden traps

Lowercase method: "patch" — and the server returns 405. Per the Fetch standard, the browser uppercases only six methods by itself: GET, POST, PUT, DELETE, HEAD and OPTIONS. PATCH isn't on that list. Write "patch" and it goes out lowercase, and most servers don't know such a method. Node.js even prints a warning about it to the console. The browser stays silent. Always write "PATCH".

null in PATCH can mean “delete.” There's a popular format called JSON Merge Patch. In it, { "phone": null } doesn't write an empty value — it removes the field. If you want an actual empty value, check how your server handles it.

A plain HTML form can't do PUT or PATCH. <form method="..."> only has GET and POST. That's why frameworks hide the real method in a hidden _method field and the form goes out as POST.

Both methods trigger a CORS preflight. If the frontend and API are on different domains, the browser first asks permission with an OPTIONS request. The server must list PUT and PATCH in Access-Control-Allow-Methods. Otherwise you get a CORS error, even though GET and POST worked.

In practice, the server decides. The standard describes how methods are supposed to behave. Server code is written by people. In Rails, for example, PUT and PATCH go to the same update action. In PostgREST, which powers the Supabase API, PATCH is a normal update, while PUT is insert-or-replace for a single row. And there you must send all its columns. Always check the specific API's docs.

Which one fits whom

Pick PATCH if the user edits part of an object. Change an avatar, flip a setting, mark a task done. That's nine cases out of ten in a typical app.

Pick PUT if the client really knows the whole object and wants to replace it. Save a document from an editor. Upload a file to a known address. Write settings that are always stored as one block. PUT's bonus: it's safe to repeat. If the request dropped, just send it again.

If AI generated your API, check one thing: what the update handler does with fields that aren't in the request. If it erases them and you send pieces, change the method or the logic. Otherwise you'll get vanishing names.

Can I just do everything with POST?

You can, and many APIs live that way. But then the client can't tell whether repeating a request is safe. PUT and PATCH say it right in their names.

Is PATCH always a partial update?

In meaning — yes. But the body format varies: sometimes it's a plain object with fields, sometimes a list of operations like “add,” “remove,” “replace.” Which format the server expects is in its docs.

What should a PUT or PATCH return on the server?

Most often — the whole updated object with code 200. That way the client doesn't need an extra GET to see the result. If you don't return a body, answer with 204.