CODEWITHSUNDEEP
resthttphttp-status-code-404http-status-code-200
Kamil Murawski
Kamil Murawski

Reputation: 240

HTTP 200 (not 404) status for an empty list result returned from a REST endpoint

Please give me examples of official specification, or trusted recommendations that can prove my business partner that when they return an empty list from a REST endpoint, the HTTP status should be 200, not 404. For me RFC-2616 is obvious, but also general and doesn't discuss the case of an empty set as a result. I'm looking for strong arguments for a discussion.

Kind regards, Kamil.

Upvotes: 4

Views: 2506

Answers (4)

herman
herman

Reputation: 12305

It depends on whether the empty list is returned simply because that is the current state of the requested resource, or because the URL used by the client was not correct.

See https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4 :

10.4 Client Error 4xx

The 4xx class of status code is intended for cases in which the client seems to have erred.

If there is no client error, any 4xx response including 404 is not appropriate.

Also, the spec continues:

Except when responding to a HEAD request, the server SHOULD include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition.

So if the response is [] (empty list in JSON) and no error message, that is another indication that 404 is not appropriate. It's also possible that 404 is appropriate but the response is lacking the error message.

Upvotes: 0

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57194

Please give me examples of official specification, or trusted recommendations that can prove my business partner that when they return an empty list from a REST endpoint, the HTTP status should be 200, not 404. For me RFC-2616 is obvious, but also general and doesn't discuss the case of an empty set as a result.

As noted by @Vasiliy Faronov, RFC 7231 describes the semantics of 200 OK; "You asked for a current representation of the resource, here it is."

It's important to recognize that the status code is meta-data, describing the nature of the response within the application domain of document transport. It doesn't tell you anything about the domain specific interpretation of the document itself.

I'm looking for strong arguments for a discussion.

https://www.google.com/search?q=C71151CF-5D9B-412F-A0EF-EBE90782800C

If you submit a query like that to google, you are going to get back an HTML page in response which reads, in part:

Your search - C71151CF-5D9B-412F-A0EF-EBE90782800C - did not match any documents.

The status line returned by Google's server returned:

HTTP/2.0 200 OK

And that's right - within the document transfer domain, everything was OK: our request was sensible, the server was able to locate a current representation of the document we asked for, we were allowed to access it, and so on.

The search-domain specific information is in the message-body, which tells us that there were no documents available that match the thing we were searching for.

Upvotes: 1

Julian Reschke
Julian Reschke

Reputation: 41997

You won't find anything "official". REST is just an architectural style, which can be applied to the use of HTTP.

My take: if the resource identifies a container of some sort, and the container exists, but is empty, it should be 200. If the container does not exist, 404. So it largely depends on the definition of the resource.

Upvotes: 2

Vasiliy Faronov
Vasiliy Faronov

Reputation: 12310

RFC 2616 is an obsolete document. The current specification for the 404 status code is RFC 7231 § 6.5.4, which seems clear enough to me:

The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.

If the empty list is a valid representation of your resource (as opposed to an error message, for example), this precludes 404.

Upvotes: 3

Related Questions