belgif / rest-guide

REST Guidelines of Belgian government institutions
https://www.belgif.be/specification/rest/api-guide/
Apache License 2.0
25 stars 4 forks source link

Allow 204 as the HTTP code for GET #191

Closed mikhailian closed 1 month ago

mikhailian commented 3 months ago

Hello,

While the text of the Belgif warns against the use of code 204 in response to GET, the diagram it links to seems to allow it.

I'd like to further challenge this warning with a real-life example.

One of my applications checks if a user responded to a meeting invitation by issuing a GET request. If the user responded to the invitation, the application returns or yes or no and the timestamp. If not, I'd like to return 204 No Content as the most obvious answer.

pvdbosch commented 3 months ago

Hi @mikhailian , what's the path of the operation in your example? Something like GET /invitations/{invitationId}/responses/{userId} ?

Something can be said for using "204 No Content" instead of "404 Resource Not Found" if the caller is expected to call an URL that doesn't represent a resource (yet). Not a very common case though, so we'd need to explain the use case to avoid misuse of 204.

Another way of modelling it, would be by adding a "hasReplied" boolean to the 200 response payload.

I'll put this up for discussion in the REST guide WG.

pvdbosch commented 1 month ago

Similar discussions:

But no clear conclusions...

A reason for 204 instead of 404 for something like /invitations/{invitationId}/responses/{userId} can be that it's easier to distinguish no response to invitation from a non-existing invitationId.

You also could provide an empty JSON object {} with a 200 in this case, or let user parse the 404 problem content to distinguish both cases.

The guideline [stat-codes] specifies "SHOULD" (not "MUST") so still leaves some room to deviate if properly motivated.

I'd suggest to leave the guidelines as-is, because these are very rare use cases that are hard to document, and removing the restriction for GET could lead to more misuse for other use cases where 404 should be used. To discuss further with WG members.

pvdbosch commented 1 month ago

feedback of REST WG: 204 could be considered in this particular case (there are arguments for and against it), but the REST guide won't be updated. Sufficient that it covers most common use cases, and motivated exceptions are still allowed.