I have 2 resources User and Album. A user has a list of albums. To get albums there are 2 REST API.
user/{userId}/albums/{albumId} gets album by albumId. If not found returns 404
user/{userId}/albums gets all albums by userId. In this case, if a user has no albums, what should be the status code 204 or 404?
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
[]
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.
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.
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.
Let me give my 2 cents on this. I hope you already know the difference between 404 vs 204.
The scenario i would prefer to use each status code are :
404 Status Code
404 means that the Resource not found or doesn't exist or URL is invalid
For example
GET : https://api.myapp.io/product/product_id_123
GET : https://api.myapp.io/image/nokia.jpg
If the single product / resource item doesn't exist in database or in resource folder, that means the resource of this URL is invalid so we have to throw 404 and Search Engines like Google & bing will not going to cache the result and will not retry again the next day for fresh content.
204 Status Code
204 means that the URL is valid and Server has successfully did the execution but it has no data to return.
For example
GET : https://api.myapp.io/product/search?keyword=nokia
If there is no data matched (single or multiple) for the keyword in database to return back the results, then throw 204 because there is no data to return but the URL is still valid and Search Engines like Google & bing will retry again the next day for fresh content because for them it is not invalid url and when you retry the next day there might be some data which matches the query.
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!
Related
/persons?age=18
Imagine a search does not return any results (means: no entity found for the request).
If I'd return a 404 here, that would suggest that maybe the /persons path is invalid entirely.
Is there any accepted status code that could be return if the request was valid in general (means: the path exists, and the request parameters have been valid), but still there is no data to return?
204 is not suitable either, as this is used to tell the user "your request was 200 OK, but there will never be a response body to your request" (like for modifications).
Is there any accepted status code that could be return if the request was valid in general (means: the path exists, and the request parameters have been valid), but still there is no data to return?
200 is appropriate when the resource has a representation, even if that representation is an empty list.
# Request:
GET /persons?age=18
# Response:
200 OK
[]
Think "web search page that returns no results", downloading an empty file.
Jim Webber's 2011 talk may help with perspective here: the status codes and headers belong to the "transferring documents over a network" domain, not to your domain application protocol. The components that are specific to your application should be paying attention to the messages in the body of the response; the meta data is directed at general purpose components that are transferring documents.
Actually you should return 200.
The number of entities found does not change the http code.
I'm building a REST API and have a dilemma around the returning response code to a GET operation.
I've found many examples and answers online but not for my particular scenario.
Here is what I have found and understand so far:
if returning an empty list (say /library/authors/{authorId}/books) an empty list with a response code 200 will suffice
if requesting a specific resource with an id ( say /library/authors/{authorId}/books/{bookId} ) the response will be empty with a 404
That summarizes most of my use cases and I am fine with it.
However, what happens if I access a sub-resource without an id?
For example, for arguments sake, let's say the author can have many books, but only one auto-biography. He either has one or he doesn't. I don't expect the user to pass in the auto-biography id because the system can figure out on its own if one exists, the endpoint is something like this:
GET /library/authors/{authorId}/auto-biography
If the author exists but he has no autobiography (it is NULL), would the http response code be:
204 (empty content)
404 (resource does not exist)
Thank you in advance!
Working through the semantics
GET /library/authors/1/auto-biography
/library/authors/1/auto-biography is an identifier. The resource itself is some concept like "the auto biography of author 1"; notice that we can talk about the resource even though it may not actually exist yet.
A resource can map to the empty set, which allows references to be made to a concept before any realization of that concept exists
The thing that appears in the body of the HTTP response isn't the resource, but a representation of the resource.
So now look at the status codes
404
The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
204
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.
A loose analogy: suppose you try to get the contents of a file. 404 is semantically aligned with FileNotFound; 204 indicates the file is zero bytes long.
404 would normally be accompanied by "a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition." It indicates that the client tried to use a link that shouldn't have been available.
204, on the other hand, doesn't have anything -- the representation is zero bytes long, how could there be data. It's a special case of a 200 response, advising the client (and intermediary components) that the response body is intentionally left blank.
I am having 2 services-
1. Client Service
2. Feature Service
Client Service asks feature service for feature corresponding to a client. If in the database no feature found for a client should what should we return?
1. 404 no resource found
2. 204 Success - No content
3. 200 Success - {features:[]} // Empty list
In practice, I have always returned a 200 with an empty list. The fact that the list is empty tells the consumer that, although nothing went wrong with the request, there are no resources associated with it.
The 204 is a fair compromise between the 200 and the 404 but I think that it adds minimal value.
I would personally shy away from throwing a 404 on an endpoint that returns a list since it is expected that there will be situations where the list is empty (that is potentially too broad of a statement). If the request was failing because of the resource associated with the list then I would definitely consider the 404 valid (let's say you had a user with a list of hats and the request for the hats was for a NOT FOUND user).
HTTP response should be 200, Just show "empty" result in TAG
You can return in two ways. 404 is not valid if no content is present.
a) 204 No Content
Explaination: The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.
b) Return 200 and with empty body {};
You can find more at w3 https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
I have
/rest/drink/categories?alcohol=true
which is return 200 status code with list of drink categories that have alcohol in it, e.g.
200 ['wine','beer']
I wonder what status code should I use, if a user hit a none handled path like below
/rest/drink
or
/rest/drink?alcohol=true
404 - Not found if the URL does not exist,
400 - Bad request if the URL exists but the request parameter is invalid.
Http has status for such conditions.
4XX defines the error is from client side and needs a change.
Wiki says
The 4xx class of status code is intended for situations in which the client seems to have erred. Except when responding to a HEAD request, the server should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents should display any included entity to the user.[31]
For the condition where it is mentioned, its ideal to use 404 - Not Found or 400 - Bad Request
This gives list of all the status codes and appropriate explanation.
W3Org
defined the specifications for these.
When a client invokes my REST-ful service, it needs to know if the response came back was 'from me' or rather a diagnosis from the containing web server that something awful happened.
One theory is that, if my code is called, it should always return an HTTP OK(=200), and any errors I've got to return should be just represented in the data I return. After all, it's my code that gets the response, not the naked browser.
Somewhat self-evidently, if I'm using REST to generate HTML read directly by a browser, I absolutely must return an error code if there's an error. In the case I care about, it's always Javascript or Java that is interpreting the entrails of the response.
Another possibility is that there is some family of HTTP status codes that I could return with a high confidence that it/they would never be generated by a problem in the surrounding container. Is this the case?
I use the following:
GET
200 OK
400 Bad Request (when input criteria not correct)
POST
202 Accepted (returned by authorization method)
401 Unauthorized (also returned by authorization)
201 Created (when creating a new resource; I also set the location header)
400 Bad Request (when data for creating new entity is invalid or transaction rollback)
PUT
Same as POST
201 Ok
400 Bad Request
DELETE
200 OK
404 Not Found (same as GET)
I would not know how to avoid that some container returns codes like 404.
4xx codes are meant to handle client errors along with possibly some entity that describes the problem in detail (and thus would mean a combination of both of your mentioned approaches). Since REST relies on HTTP and the according semantics of status as well as methods, always returning 200 in any possible case is a violation of this principle in my opinion.
If you for instance have a request such as http://foo.com/bar/123 which represents a bar ressource with id=123 and you return 200 with some content, the client has no chance to figure out if this was the intended response or some sort of error that occured. Therefore one should try to map error conditions to status codes as discussed in REST: Mapping application errors to HTTP Status codes for example.