Proper REST response for empty table?

Question

Let's say you want to get list of users by calling GET to api/users, but currently the table was truncated so there are no users. What is the proper response for this scenario: 404 or 204?

Imperator

I'd respond with 200 and an empty collection (not an empty response body but rather a collection with no elements inside, this will look different depending on the format returned) – Laurence

404 in this context would probably be better suited for 'table not found'. I'd say return an empty list. – Bowyer

Possible duplicate of What is the proper REST response code for a valid request but an empty data? – Brookite

@EJoshuaS It's not. Both questions are mine and very old. They are similar but not duplicates. – Imperator

@EJoshuaS They are obviously not duplicates. This question is about /api/users while that one is about /api/users/1. – Hobbie

Answer 1

I'd say, neither.

Why not 404 (Not Found) ?

The 404 status code should be reserved for situations, in which a resource is not found. In this case, your resource is a collection of users. This collection exists but it's currently empty. Personally, I'd be very confused as an author of a client for your application if I got a 200 one day and a 404 the next day just because someone happened to remove a couple of users. What am I supposed to do? Is my URL wrong? Did someone change the API and neglect to leave a redirection.

Why not 204 (No Content) ?

Here's an excerpt from the description of the 204 status code by w3c

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

While this may seem reasonable in this case, I think it would also confuse clients. A 204 is supposed to indicate that some operation was executed successfully and no data needs to be returned. This is perfect as a response to a DELETE request or perhaps firing some script that does not need to return data. In case of api/users, you usually expect to receive a representation of your collection of users. Sending a response body one time and not sending it the other time is inconsistent and potentially misleading.

Why I'd use a 200 (OK)

For reasons mentioned above (consistency), I would return a representation of an empty collection. Let's assume you're using XML. A normal response body for a non-empty collection of users could look like this:

<users>
  <user>
    <id>1</id>
    <name>Tom</name>
  </user>
  <user>
    <id>2</id>
    <name>IMB</name>
  </user>
</users>

and if the list is empty, you could just respond with something like this (while still using a 200):

<users/>

Either way, a client receives a response body that follows a certain, well-known format. There's no unnecessary confusion and status code checking. Also, no status code definition is violated. Everybody's happy.

You can do the same with JSON or HTML or whatever format you're using.

Laurence

Definitely agree. And for REST, I would simply send back a status code of 200 with an empty array: []. – Selmore

Makes sense. No need to make it harder. 404 would be confusing. – Raymundorayna

Lets assume API which describe coins in you pocket, with endpoints: GET /singleCoin - returns random single coin from your pocket,GET /severalCoins- returns some coins from your pocket you can grab in one time. Lets say you have no coins in your pocket at now. When you ask to GET /singleCoin you'll get 404 Not Found, but when you ask to GET /severalCoins you'll get 200 OK with empty list []. One fact - you have no coins, described with different responses, why? I whould say it's better always to get 404 Not Found, because there is no coins found in your pocket. – Binturong

@Binturong It depends on what you mean by GET /severalCoins. If you mandate that GET /severalCoins must return some coins then it shouldn’t be 200 because it’s not OK; server failed to provide what client want. For /singleCoin this is obvious because client want exactly one coin, no more, no less. This is same for /coins/7. In contrast for /coins endpoint, typically clients expect no coin, one coin, or multiple coins. All of them are valid response. If there's no coin, then this is what they want. It’s like an emply List<Coin> in Java, instead of null. – Hobbie

Besides, 404 is for client errors. From the docs > "The 4xx class of status code is intended for cases in which the client seems to have erred." – Jaw

Answer 2

I'd answer one of two codes depending on runtime situation:

404 (Not Found)

This answer is pretty correct if you have no table. Not just empty table but NO USER TABLE. It confirms exact idea - no resource. Further options are to provide more details WHY your table is absent, there is couple of more detailed codes but 404 is pretty good to refer to situation where you really have no table.

200 (OK)

All cases where you have table but it is empty or your request processor filtered out all results. This means 'your request is correct, everything is OK but you do not match any data just because either we have no data or we have no data which matches your request. This should be different from security denial answer. I also vote to return 200 in situation where you have some data and in general you are allowed to access table but have no access to all data which match your request (data was filtered out because of object level security but in general you are allowed to request).

Heterothallic

Answer 3

If you are expecting list of user object, the best solution is returning an empty list ([]) with 200 OK than using a 404 or a 204 response.

Enshroud

This is a duplicate of the accepted answer, with less explanation. – Gman

Answer 4

definitely returns 200.

404 means resource not found. But the resource exists. And also, if the response has 404 status. How can you know users list empty or filled?

---

• '/users' if is empty should return '200'.
• '/users/1' if the id is not found. should return 404.

Eskridge

This is a duplicate of the accepted answer, with less explanation. – Gman

Answer 5

It must 200 OK with empty list.

Why: Empty table means the table exists but does not have any records.

404 Not Found means requested end point does not exist.

Befriend

This is a duplicate of the accepted answer, with less explanation. – Gman