HTTP status code for a REST search without result

Question

I have a REST endpoint for a search.

GET /person?firstname=john&name=smith

As result a collection with the HTTP status code 200 OK is returned:

[
   {
      "id":11,
      "firstname":"John",
      "name":"Smith",
      "birthday":"1996-03-08"
   },
   {
      "id":18,
      "firstname":"John",
      "name":"Smith",
      "birthday":"1963-07-11"
   }
]

What is the correct HTTP status code and payload for a empty search result?

HTTP Status 200 OK with a empty collection []
HTTP Status 204 No Content with a empty collection []
HTTP Status 204 No Content with a empty body

I'd suggest 200 because an empty list or a list with items is really the same thing, one is just a special case. Also 204 means literally no content at all while "[]" is still some content. — laurent, Jul 17 '17 at 19:57
Possible duplicate of [HTTP 200 or 404 for empty list?](https://stackoverflow.com/questions/30217761/http-200-or-404-for-empty-list) — CodeCaster, Jul 17 '17 at 20:11
https://stackoverflow.com/questions/13366730/proper-rest-response-for-empty-table, and so on — CodeCaster, Jul 17 '17 at 20:12

JuanR · Accepted Answer · 2017-07-17T20:14:28.817

5

I would recommend:

HTTP Status 200 OK with a empty collection []

The reason is that 204 means there is no content to send back and that is not what the result of your call is.

In your case, there IS something to send back. It's a Json result that happens to be composed of an empty collection.

UPDATE:

From the HTTP protocol definition:

10.2.5 204 No Content: The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.

And:

The 204 response MUST NOT include a message-body, and thus is always terminated by the first empty line after the header fields.

edited Jul 17 '17 at 20:14

answered Jul 17 '17 at 19:57

JuanR

7,405
1
19
30

_"no more content"_ - citation required. – CodeCaster Jul 17 '17 at 20:01
@CodeCaster: I added the relevant paragraphs. – JuanR Jul 17 '17 at 20:14
That doesn't say that 204 means _no more_ content. – CodeCaster Jul 17 '17 at 20:17
1

Which is why I updated the answer too, if you notice. – JuanR Jul 17 '17 at 21:24

score 4 · Answer 2 · answered Jul 17 '17 at 19:56

4

IMO the first case:

HTTP Status 200 OK with a empty collection []

Then you don't have to check for the 204 and use what is returned, which is an empty list.

answered Jul 17 '17 at 19:56

LLL

3,566
2
25
44

1

You beat me to it =) Your search yielded no matching results, but you can still treat the result the same as if something did in fact match. – Justin Jul 17 '17 at 19:59

score 2 · Answer 3 · answered Jul 17 '17 at 19:59

This is a matter of convention here when you are designing your web application. 200 ok with an Empty collection would be my way to go . Because :

It proved that your API does return response
Handling 200 would be much easier on client-side , as I may assume you are working with Javascript , where other response code might throw you an error

HTTP status code for a REST search without result

3 Answers3

Linked