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

[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.

[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.

[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.