REST API - Handling an empty body in PATCH

Question

I am currently contributing to a REST API written in Go and I was facing an existential question.

How are we supposed to handle an empty body in a PATCH? Knowing that a PATCH is used to update an existing data, are we supposed to return an error code (4XX) or an ok status (2XX)?

For example, if I have the following route: /user/:id

And a user has the following structure:

type User struct {
  Name string
  Email string
}

So if we PATCH a specific user, we will either have a body containing the name or the email.

What should we do if it is empty?

The RFC5789 was not a real help (2.2 for error handling)

https://datatracker.ietf.org/doc/rfc5789/?include_text=1

Answer 1

How are we supposed to handle an empty body in a PATCH?

That depends: what's wrong with an empty patch body?

If an empty patch body is an error, then your response should communicate the nature of the error to the client.

If the empty patch body is not an error, then apply the empty patch. That's probably a no-op, in which case, success! So you return a response that explains that applying empty patches is trivial, and here's where they can go to see the updated implementation. Alternatively, you can 204 as shown in the example. I don't see things explicitly spelled out, but I think you can draw upon the pattern described in RFC 7231 section 6.3.1.

Some examples that might help.

Suppose the client were using JSON Patch as the media type for the request. Now, a "JSON Patch document is a JSON [RFC4627] document that represents an array of objects". An empty request body is not a valid JSON document, and certainly isn't a valid array of objects, so that's a malformed patch document, and as described in section 2.2 you should be thinking about sending a 400 response.

Suppose the client were to send a json patch with an empty array of operations

[]

Semantically, that's a no-op -- except that a response indicating that the patch was successfully applied will invalidate cached values. So you could certainly report success (200) with not doing anything. You may be able to prevent the cached entries from being invalidated by returning an error (I think the Patch spec isn't quite describing the semantics correctly, but I don't see an errata filed).

A similar argument applies for application/merge-patch+json.

You may also want to consider the errata for RFC 5789

If a server receives a PATCH request with a media type whose specification does not define semantics specific to PATCH, the server SHOULD reject the request by returning the 415 Unsupported Media Type status code, unless a more specific error status code takes priority.

In particular, servers SHOULD NOT assume PATCH semantics for generic media types that don't define them, such as "application/xml" or "application/json".