HTTP GET Request Status 204 Vs 404

Question

I have 2 resources User and Album. An user has a list of albums. To get albums there are 2 REST API.

1. user/{userId}/albums/{albumId} get album by albumId if not

Answer 1

When you ask for a specific resource, say a user, and the user doesn't exist, then you should return 404. For example, you have an API to retrieve a user using the following URL:

https://yourdomain.com/api/users/:userid

and a request is made to retrieve user 1234, that doesn't exist, then you should return 404. In this case, the client requested a resource that doesn't exist.

https://yourdomain.com/api/users/1234 
404

Now suppose you have an api that returns all users in the system using the following url:

https://yourdomain.com/api/users

If there are no users in the system, then, in this case, you should return 204.

Answer 2

Here is what the RFC2616 that defines the HTTP protocol says about Status-codes:

The first digit of the Status-Code defines the class of response. The last two digits do not have any categorization role. There are 5 values for the first digit:

  - 1xx: Informational - Request received, continuing process

  - 2xx: Success - The action was successfully received,
    understood, and accepted

  - 3xx: Redirection - Further action must be taken in order to
    complete the request

  - 4xx: Client Error - The request contains bad syntax or cannot
    be fulfilled

  - 5xx: Server Error - The server failed to fulfill an apparently
    valid request

In your case, the request was successful, but there are no albums to show, so you definitely should use a status from the 2xx category.

Here is what the RFC says about the 204 status:

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. The response MAY include new or updated metainformation in the form of entity-headers, which if present SHOULD be associated with the requested variant.

If the client is a user agent, it SHOULD NOT change its document view from that which caused the request to be sent. This response is primarily intended to allow input for actions to take place without causing a change to the user agent's active document view, although any new or updated metainformation SHOULD be applied to the document currently in the user agent's active view.

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

The RFC states that the 204 is primarily intended to allow inputs, so you shouldn't use this one. I would use the 200 in this case.

Answer 3

Is the absence of any album really seen as an error? Assuming the albums are returned as a JSON array, the common response to such a situation would be a HTTP 200 with an empty array as the body.

Returning 404 signals that the resource doesn't exist, kind of saying that it isn't even possible to ask for the list of albums for this particular user. But in fact, it's possible to successfully return the list of albums, it's just that the list is empty. It doesn't seem at all exceptional to me. This is completely in contrast to retrieval of one specific album using an ID that doesn't exist (using your other endpoint); in such a situation a 404 is correct.

While a 204 seems better than a 404, because it at least tells the client that the request was successful but had no content, its intention is not really to be used to signal a "successful absence". Rather, it signals that the resource DOES exist but for some reason the server chose not to include the resource in the response body - for example the purpose of the request could have been to simply pass back some headers to the client.

A 204 can also be used as a response to a POST request where some action was carried out by the server without necessarily creating any new resource (which would have implied a 201 CREATED), or where it's for some other reason not relevant to return any resource.

I think it's clear that what you need is a

GET /user/xxx/albums

HTTP/1.1 200 OK

[]

Answer 4

I agree with the responses, but I think is 204 or 200, it depends of your response when the album list is empty.

If you will return a empty array, the return it with 200 code, if you prefer to don't return anything, then the right one will be 204. (I prefer a 200 with empty list)

Only use 404 with a resource doesn't existis, if it is a empty list the choose 204 or 200.

Good hacking man!

Answer 5

Error Code 404

The web site hosting server will typically generate a "404 Not Found" web page when a user attempts to follow a broken or dead link.

Return Code 204

The server has fulfilled the request but does not need to return an entity-body.

Conclusion

You obviously need to return a 204 status code. If you use the 404 one, the user may be disturbed. More, you use 404 when the targeted album doesn't exist. Using 404 for both 1 and 2 is illogical.