HTTP status code for an empty result

[Guilherme Gossling Valerio]

Hi All,

Love all the great info and tips you guys provide about APIs, so thanks a lot.
My question is whether to return a 200 or a 404 when a list returned by a call is empty.

e.g. user 123 doesn't have any friends, so when I hit /api/v1/users/123/friends using a GET, I was returning a 200 OK with an empty array (as the request is successful, even though it returns no friends).

my business partner, who is building the app which uses the API asked me to return a 404 when that happens, as no users were found. I understand where he is coming from, but still not sure if that is the correct thing to do.

What do you guys think? Thanks in advance!

G

[Jack Repenning]

On Mar 20, 2012, at 2:27 PM, Guilherme Gossling Valerio wrote:

my business partner, who is building the app which uses the API asked me to return a 404 when that happens, as no users were found. I understand where he is coming from, but still not sure if that is the correct thing to do.

This appears to be a misunderstanding of what 404 means. Status 404 means "the web page you requested could not be found." Or, extended to a REST context, "the REST resource you requested doesn't exist." In your story, the login is fine, the search is performed, but it happens to have no results. That's still a status 200, I believe: "your request was processed properly and successfully, and here's the (empty) result." It's the difference between "you question makes no sense" (404) and "the proper answer to your question is silence" (200).

Jack Repenning

Bill Gates has won

I've got the postmodern blues

- postmodern blues

  Patricia Barber

[Abraham Williams]

I recommend 204 No Content as the request was successful. On list methods a 404 makes me think the API method does not exist.

Abraham
--
Abraham Williams | InboxQ | abrah.am | abraham+

@abraham | github.com/abraham | blog.abrah.am
This email is: [ ] shareable [x] ask first [ ] private.

[Carlos Eberhardt]

I almost like 200 better with a body indicating zero friends (forever alone?). But then again, I might be missing the beauty of the 204. 

In any case 4xx should mean possible client error of some sort, which this doest seem to be.

Thanks,

Carlos

[Pablo Molnar]

I follow a similar rule:

- Collection resources (/users/me/friends, /items/$id/pictures, ...) --> 200 with an empty list

- Object resource (/items/$id, /users/me/thumbnail, ...) --> 404 with an error message

Pablo

[Joe Gilvary]

I agree with Abraham. This sounds like the precise use case for 204.
The request completed successfully. There is no body to return. No
client error implied.

A 404 would seem to imply there is no such resource (null), not that
it's an empty set.

Thanks,

Joe


On Mar 20, 5:27 pm, Guilherme Gossling Valerio <ggu...@gmail.com>
wrote:

[Richard Tuin]

I recommend using the 200 status for empty collections, as there is a message body (an empty array in your case).

This confirms that the request was valid and successful, but says nothing about the contents of the message body (and in this context, it shouldn't!)

I recommend not using the HTTP status code 204 for this, because RFC 2616 defines the following about it:

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

Source: http://tools.ietf.org/html/rfc2616#section-10.2.5

Greetings,

Richard Tuin

2012/3/21 Joe Gilvary <feral...@gmail.com>

[Pablo Molnar]

I agree with Richard. 200 status with an empty list would suit better.

Pablo

[Peter Robinett]

Just another +1 for 204.

[Chris O'Dell]

I also agree with Richard that a 200 with an empty list makes more sense from the point of the consumer, who would need to handle a 204 without a body differently from 200 with an empty list.  This seems confusing...  It's not as if there's no resource to return - it's an empty collection resource.

Chris

[Jeff Schmidt]

For what it's worth, +1 for 200. IMHO, an empty list is still content.

Jeff

On Mar 21, 10:12 am, "Chris O'Dell" <christine.ann.od...@gmail.com>
wrote:

> I also agree with Richard that a 200 with an empty list makes more sense
> from the point of the consumer, who would need to handle a 204 without a
> body differently from 200 with an empty list.  This seems confusing...
>  It's not as if there's no resource to return - it's an empty collection
> resource.
>
> Chris
>

> On 21 March 2012 13:47, Pablo Molnar <pablomol...@gmail.com> wrote:
>
>
>
>
>
>
>
> > I agree with Richard. 200 status with an empty list would suit better.
>
> > Pablo
>

> > On Wed, Mar 21, 2012 at 8:51 AM, Richard Tuin <richardt...@gmail.com>wrote:
>
> >> I recommend using the 200 status for empty collections, as there is a
> >> message body (an empty array in your case).
> >> This confirms that the request was valid and successful, but says nothing
> >> about the contents of the message body (and in this context, it shouldn't!)
>
> >> I recommend not using the HTTP status code 204 for this, because RFC 2616
> >> defines the following about it:
>
> >> "The 204 response MUST NOT include a message-body, and thus is always
> >> terminated by the first empty line after the header fields."
>
> >> Source:http://tools.ietf.org/html/rfc2616#section-10.2.5
>
> >> Greetings,
>
> >> Richard Tuin
>

> >> 2012/3/21 Joe Gilvary <feraldr...@gmail.com>

[Joey Lowe]

+1 for 200. I would think an empty list is the same as a full list, just
empty. :)

[Guilherme Gossling Valerio]

Great, thanks Peter. 

I was trying to restrict the number of different codes returned by the API, but that one fits like a glove.

[Peter Robinett]

Glad it helps.

I am a big believer in embracing the HTTP standard rather than inventing my own formats in response bodies, so I like to make as much use as possible for status codes, methods, and other headers. Beyond 204 I would also recommend considering the 304 code for responses to conditional requests.

I have a presentation that goes into these various topics (maybe start around page 34): http://www.bubblefoundry.com/blog/2011/08/mobile-api-talk-slides/

Cheers,

Peter

[Abraham Williams]

The reason I think a 204 is best is an empty list is would be returned with a 200. Since it is an empty list you might as well skip the step of encoding an empty list with no content for the response body and just use a 204 which is designed to mean that there is no content.

As for the argument that a 204 adds complexity for the app in my experience it generally will not. E.g.

if status_code == 200:

  if response.length > 0:

    save(response)

  else: 

    display(error)

changes to

if status_code == 200:

  save(response)

else if status_code == 204: 

  display(error)

Granted this is greatly simplified in pseudo code but you get the idea.

On Wed, Mar 21, 2012 at 04:51, Richard Tuin <richa...@gmail.com> wrote:

I recommend not using the HTTP status code 204 for this, because RFC 2616 defines the following about it:

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

Why does this matter?

[Richard Tuin]

2012/3/21 Abraham Williams <4br...@gmail.com>

The reason I think a 204 is best is an empty list is would be returned with a 200. Since it is an empty list you might as well skip the step of encoding an empty list with no content for the response body and just use a 204 which is designed to mean that there is no content.

 

As for the argument that a 204 adds complexity for the app in my experience it generally will not. E.g.

if status_code == 200:

  if response.length > 0:

    save(response)

  else: 

    display(error)

changes to

if status_code == 200:

  save(response)

else if status_code == 204: 

  display(error)

Granted this is greatly simplified in pseudo code but you get the idea.

This definitely makes sense in some situations.

Using a 204 No Content and therefore skipping the step of representing an empty collection is one of the possibilities. However, it is a choice you have to make consciously.

The API's i have worked on all treat collections as resources. Meaning collections can contain metadata (outside HTTP headers).

Think of things like links (hypermedia setup) or collection properties. Examples of collection properties are a filter start- or enddate, or pagination information.

 

On Wed, Mar 21, 2012 at 04:51, Richard Tuin <richa...@gmail.com> wrote:

I recommend not using the HTTP status code 204 for this, because RFC 2616 defines the following about it:

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

Why does this matter?

This only matters if you do have a representation of an empty collection coming from your service.

Greetings,

Richard Tuin

[Manuel Puig]

Hi all,

I like 204 for empty responses, even if it's for individual resource, not list. However, when you think about caching 200 would make more sense since it can be cached (TTL). 

Imagine you get a call to get some resources and the result is empty. With 200 and empty list and cache controls enabled, it will be cached and further request won't hit backend systems. Using 204 will hit it all the time.

Anybody knows an elegant way to use 204 with cache? Maybe with ETag?

With 200 the problem is what I return for a single objects (get by id for example). Cannot return  empty list :( should I fake JSON object to add something in the body?

Thanks,

[John McCarthy]

I was searching around for 200 vs 204 discussion on an empty REST collection, and am glad I found this discussion and group.  You all bring out excellent points for either 200 with an empty collection or 204 with no content (I agree that 404 is a bad approach).  Like Peter, I feel that 204 fits well (successful but no content) and seems to embrace the HTTP standard.  After noticing that Rails by default favors a 200 with an empty array for JSON responses and reading the other comments here, I see how that can be a consistent result as well.  Granted, either way, consistency in the API is important (choose 204 or 200 with an empty collection but use that pattern consistently in the API).

Browser behavior adds another interesting wrinkle to this discussion.  Navigating to a URL that returns 204 in Chrome, Firefox, and IE results in an aborted or cancelled request.  These browsers all stay on the current page while showing the new URL in the address bar.  This has confused me when using a browser to inspect a REST API.  Chrome and IE developer tools also make this look like a kind of request failure (show status cancelled in Chrome dev tools), and I have to dig into the result to see that it was actually a 204.  I don't know why browsers don't simply display a blank page like about:blank (although I'm sure there's a reason).  On the other hand, if the API returns a 200 with an empty collection, the browser will simply navigate to that URL and display the empty array.  To me, browser behavior for 204 violates the principle of least astonishment (at least, it astonished me), and this pushes me towards using 200 with an empty collection.

Also came across Mark Seemann's REST lesson learned: Avoid 204 responses which offers better alternatives to 204 responses.

[Theo van Hoesel]

I stumbled upon this, and think that many do not know the reason we need a 204 status.

204 No Content is merely a confirmation that the request has been understood and acted upon correctly.

Think of it like toggling tick-boxes on a web-page, rating stars, the browser shouldn't be updated after the PUT request, the user-interface already displays the new resource state.

if a search or list on a specific resource ends up in an empty list, return the empty list! a 200 OK! If that would be a list of words, Content-Length = 0!

What if the client expects a XML doc? Some DTD's or Schema's do mandate the <LIST></LIST> and is not optional, however the <ELEMENT></ELEMENT> occurrence would be zero. Do not send nothing, the client gets confused, all it wants is the response and iterate over the LIST

204, also perfect after a DELETE request where one clicks on a X at the end of a row and the UI nicely animates the deletion. The browser is expected to stay on that page.

Op donderdag 13 februari 2014 16:34:50 UTC schreef John McCarthy: