Should return empty list [] 200/204 or 404 in a Restful API design? [duplicate]

Question

For example, there's a restful API GET http://luexu.com/users/{page} to list the users in Nth page. Suppose there're 20 users in each page. There're 100 users total in the database. GET http://luexu.com/users/5 returns the 80th to 100th users.

So how about query GET http://luexu.com/users/10? it's out of the total users. Which is a better design to return an empty list, empty array [] or 404?

200?

{
    "code": 200,
    "msg": "OK",
    "data": []
}

or 204?

{
    "code": 204,
    "msg": "OK",
    "data": []
}

or 404?

{
    "code": 404,
    "msg": "Not Found",
    "data": null
}

Answer 1

so how about code 204?

In HTTP, 204 No Content means something very specific -- that the message body is zero bytes long.

The 204 (No Content) status code indicates that the server has successfully fulfilled the request and that there is no additional content to send in the response payload body.

So you shouldn't be thinking about it if you are sending, for example, a json encoded document.

If an empty list is an acceptable representation of the resource, then using 200 as the response code is fine. For instance, consider this URI for stack overflow itself.

https://stackoverflow.com/questions/tagged/cqrs+or+domain-driven-design+or+event-sourcing?sort=newest&page=999&pagesize=15

As of 2019-06-01, there are many fewer than 999 pages of questions with these tags, but the server has no problem computing the correct representation for this page (including the information that the highest numbered page is 426). Therefore, the semantics of 200 are perfectly suitable.

404 means that no representation for the resource was available. All 4xx class response codes indicate an error with the request -- in this case, it suggests that the client made a mistake with the URI. That could be a temporary condition (you shouldn't be asking about that resource right now). So that could also be fine, if what you want to indicate is that the client has left the happy path of the domain protocol.

How to choose? I start from this observation in the HTTP specification

the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.

So which is useful to the client? A representation of the problem, or a representation of an empty collection? This can be a challenging question when the same resources are being used for different things.

Answer 2

This is one of those questions that doesn't have a "best" answer.

All you can do is look at the options and choose what works best for your scenario.

As a rule of thumb, I personally avoid returning 404. The reason is that it is unclear why you got a 404. You could get a 404 because your URL is wrong, so if you make a design choice to return 404 when there is no data then you end up in an unclear situation. How do you know why you got 404? This is no good.

Returning a 200 with an empty array is perfectly fine. Returning 204 perfectly fine as well.

The important bit is to make a choice, be consistent and document the choice so the users of your API know you made this choice and why.

Consistency and clarity, aim for that.