HTTP PATCH Isn't What You Think It Is (And Neither Is PUT)

HTTP PATCH Isn’t What You Think It Is (And Neither Is PUT) Link to heading

On the surface, HTTP verbs seem simple:

• GET retrieves a resource
• POST creates one
• PUT updates it
• PATCH updates part of it
• DELETE removes it

But once you actually try to implement these correctly, especially PATCH, you quickly realize it’s not that simple.

PATCH Isn’t a Standard (Yes, Really) Link to heading

The PATCH method is defined in RFC 5789. However, unlike other HTTP verbs like GET and POST, it doesn’t define a standard way to apply the update.

Most people assume PATCH is like PUT, but for partial updates. And technically, it is. But here’s the catch: PATCH doesn’t define how the update is applied. It just says, “you can partially update a resource” — you have to define how.

You might think this is valid:

PATCH /users/123
{
  "email": "new@example.com"
}

But that only works if both the client and server agree on the patch format. And there isn’t just one.

You have options like:

• application/json-patch+json – JSON Patch (RFC 6902), which is like a set of instructions (e.g. “replace path X with value Y”)
• application/merge-patch+json – JSON Merge Patch (RFC 7386), which works more like a shallow merge
• Or your own custom format, which brings its own risks

So if you’re going to use PATCH, read the relevant RFCs first. Otherwise, you risk building something brittle, inconsistent, or unclear — especially for future developers.

The PUT/POST Mix-Up Link to heading

Another thing I see often: people confuse PUT and POST. They often use PUT to create a new resource or POST to update an existing one.

To keep it straight:

Think of PUT as “I’m replacing this resource at this URI.” If it doesn’t exist yet, it’s created. But that’s usually discouraged unless your resource IDs are client-generated.

So What Should You Do? Link to heading

If you’re building a typical API, here’s what I recommend:

• Use POST to create resources.
• Use PUT for full updates when the client can send all the data.
• Only use PATCH if:
  • You’ve picked a proper patch format (like JSON Patch or Merge Patch).
  • Your consumers understand that format.
  • You’ve read the RFCs and know what edge cases you’re exposing.

If not, you’re better off with targeted POST endpoints like:

POST /users/123/update-email
{
  "newEmail": "updated@example.com"
}

It might not be “REST purist” approved, but it’s clear, explicit, and hard to misuse.