When creating a resource that returns an empty body, should 201 or 204 win?

[darrelmiller]

It feels like to me that a 201 should win as a client can always look at the content-length to know there is no body.

However, in the section on managing webhook subscriptions, the guidelines say:

The service MUST return an empty body and 204 No Content to indicate a successful patch

If we apply this rigidly, it means that if the subscription API supported "upserts" then we wouldn't be able to return a 201 to indicate creation.

[garethj-msft]

I don't think we successfully reconciled the upsert guidance with the webhooks guidance here, and we usefully should. In practice the Microsoft Graph doesn't support upsert on webhooks, so we didn't run into the conflict.

[darrelmiller]

I get the feeling that there are a number of constraints on the webhooks guidance that are in additional to the regular API guidance and wonder if are essential. I'm going to read more and maybe create a separate issue addressing that.

Independent to that though, is it worth stating that in general a 201 should supersede 204 on a create.

[darrelmiller]

Based on conversations with a number of people, it seems logical to favour 201 over 204 in the case where something has been created and it has no body. A client can always use content-length 0 to detect an empty body.

[TimLovellSmith]

My 2c: 'empty content' is just different from 'no content'. 204 is for 'no content' only, not empty.

[cwoodruff]

I agree with @TimLovellSmith. There is a difference between an empty glass and no glass at all. 204 for no glass and 201 for the empty glass.

[garethj-msft]

I agree that the distinction between empty and none is served by these two codes. However, I'm struggling a bit to imagine a concrete example. If it isn't a singleton, then it needs an ID to allow future referncing to DELETE the thing that was created at minimum I woul dhave thought. If it's a singleton and has no data, then what is its utility? It sounds like a switch at that point.