What is the proper REST response code for a valid request but an empty data?

For example you run a GET request for users/9 but there is no user with id #9. Which is the best response code?

• 200 OK
• 202 Accepted
• 204 No Content
• 400 Bad Request
• 404 Not Found

I strongly oppose 404 in favour of 204 or 200 with empty data. Or at least one should use a response entity with the 404.

The request was received and properly processed - it did trigger application code on the server, thus one cannot really say that it was a client error and thus the whole class of client error codes (4xx) is not fitting.

More importantly, 404 can happen for a number of technical reasons. E.g. the application being temporarily deactivated or uninstalled on the server, proxy connection issues and whatnot.

Sure, the 5xx error class exists for such cases, but in reality the affected middleware components often have no way to know that the error is on their side and then just assume that the error is on the client side, and then respond with a 404 instead of 500/503.

Therefore based on the status code alone the client cannot distinguish between a 404 that means "empty result set" and a 404 that means "something is seriously wrong, report this error to the ops team".

This can be fatal: Imagine an accounting service in your company that lists all the employees that are due to an annual bonus. Unfortunately, the one time when it is called it returns a 404. Does that mean that no-one is due for a bonus, or that the application is currently down for a new deployment?

-> For applications that need to know that a requested resource positively does not exist instead of just being temporarily unaccessible, 404 without response entity therefore is pretty much a no-go.

Also, many client frameworks respond to a 404 by throwing an exception with no further questions asked. This forces the client developer to catch that exception, to evaluate it, and then to decide based on that whether to log it as an error that is picked up by e.g. a monitoring component or whether to ignore it. That doesn't seem pretty to me either.

The advantage of 404 over 204 is that it can return a response entity that may contain some information about why the requested resource was not found. But if that really is relevant, then one may also consider using a 200 OK response and design the system in a way that allows for error responses in the payload data. Alternatively, one could use the payload of the 404 response to return structured information to the caller. If he receives e.g. a html page instead of XML or JSON that he can parse, then that is a good indicator that something technical went wrong instead of a "no result" reply that may be valid from the caller's point of view. Or one could use a HTTP response header for that.

Still i would prefer a 204 or 200 with empty response though. That way the status of the technical execution of the request is separated from the logical result of the request. 2xx means "technical execution ok, this is the result, deal with it".

I think in most cases it should be left to the client to decide whether an empty result is acceptable or not. By returning 404 without response entity despite of a correct technical execution the client may decide to consider cases to be errors that simply are no errors.

Another quick analogy: Returning 404 for "no result found" is like throwing a DatabaseConnectionException if a SQL query returned no results. It can get the job done, but there are lots of possible technical causes that throw the same exception which then would be mistaken for a valid result.

Another perspective: From an operations point of view a 404 may be problematic. Since it can indicate a connectivity problem rather than a valid service response, i would not want a fluctuating number of "valid" 404s in my metrics/dashboards that might conceal genuine technical issues that should be investigated and fixed.

Edit: Wow, this has caused a lot of controversy. Here is another argument against 404: Strictly from a HTTP spec (RFC7231) point of view, 404 does not even mean that a resource does not exist. It only means that the server has no current representation of the requested resource available, and this even may be only temporary. So strictly by HTTP spec, 404 is inherently unreliable regarding the nonexistence of a requested thing. If you want to communicate that the requested thing positively does not exist, do not use 404.

TL;DR: Use 404

See This Blog. It explains it very well.

Summary of the blog's comments on 204:

1. 204 No Content is not terribly useful as a response code for a browser (although according to the HTTP spec browsers do need to understand it as a 'don't change the view' response code).
2. 204 No Content is however, very useful for ajax web services which may want to indicate success without having to return something. (Especially in cases like DELETE or POSTs that don't require feedback).

The answer, therefore, to your question is use 404 in your case. 204 is a specialized reponse code that you shouldn't often return to a browser in response to a GET.

The other response codes are even less appropriate than 204 and 404:

1. 200 should be returned with the body of whatever you successfully fetched. Not appropriate when the entity you're fetching doesn't exist.
2. 202 is used when the server has begun work on an object but the object isn't fully ready yet. Certainly not the case here. You haven't begun, nor will you begin, construction of user 9 in response to a GET request. That breaks all sorts of rules.
3. 400 is used in response to a poorly formatted HTTP request (for instance malformed http headers, incorrectly ordered segments, etc). This will almost certainly be handled by whatever framework you're using. You shouldn't have to deal with this unless you're writing your own server from scratch. Edit: Newer RFCs now allow for 400 to be used for semantically invalid requests.

Wikipedia's description of the HTTP status codes are particularly helpful. You can also see the definitions in the HTTP/1.1 RFC2616 document at www.w3.org

At first, I thought a 204 would make sense, but after the discussions, I believe 404 is the only true correct response. Consider the following data:

Users: John, Peter

METHOD  URL                      STATUS  RESPONSE
GET     /users                   200     [John, Peter]
GET     /users/john              200     John
GET     /unknown-url-egaer       404     Not Found
GET     /users/kyle              404     User Not found
GET     /users?name=kyle`        200     []
DELETE  /users/john              204     No Content

Some background:

1. the search returns an array, it just didn't have any matches but it has content: an empty array.

2. 404 is of course best known for url's that aren't supported by the requested server, but a missing resource is in fact the same.
   Even though /users/:name is matched with users/kyle, the user Kyle is not available resource so a 404 still applies. It isn't a search query, it is a direct reference by a dynamic url, so 404 it is.

3. After suggestions in the comments, customizing the message of the 404 is another way of helping out the API consumer to even better distinguish between complete unknown routes and missing entities.

Anyway, my two cents :)

If it's expected that the resource exists, but it might be empty, I would argue that it might be easier to just get a 200 OK with a representation that indicates that the thing is empty.

So I'd rather have /things return a 200 OK with {"Items": []} than a 204 with nothing at all, because in this way a collection with 0 items can be treated just the same as a collection with one or more item in it.

I'd just leave the 204 No Content for PUTs and DELETEs, where it might be the case that there really is no useful representation.

In the case that /thing/9 really doesn't exist, a 404 is appropriate.

In previous projects, I've used 404. If there's no user 9, then the object was not found. Therefore 404 Not Found is appropriate.

For object exists, but there is no data, 204 No Content would be appropriate. I think in your case, the object does not exist though.

There are two questions asked. One in the title and one in the example. I think this has partly led to the amount of dispute about which response is appropriate.

The question title asks about empty data. Empty data is still data but is not the same as no data. So this suggests requesting a result set, i.e. a list, perhaps from /users. If a list is empty it is still a list therefore a 204 (No Content) is most appropriate. You have just asked for a list of users and been provided with one, it just happens to have no content.

The example provided instead asks about a specific object, a user, /users/9. If user #9 is not found then no user object is returned. You asked for a specific resource (a user object) and were not given it because it was not found, so a 404 is appropriate.

I think the way to work this out is if you can use the response in the way you would expect without adding any conditional statement, then use a 204 otherwise use a 404.

In my examples I can iterate over an empty list without checking to see if it has content, but I can't display user object data on a null object without breaking something or adding a check to see if it is null.

You could of course return an object using the null object pattern if that suits your needs but that is a discussion for another thread.

To summarize or simplify,

2xx: Optional data: Well formed URI: Criteria is not part of URI: If the criteria is optional that can be specified in @RequestBody and @RequestParam should lead to 2xx. Example: filter by name / status

4xx: Expected data : Not well formed URI : Criteria is part of URI : If the criteria is mandatory that can only be specified in @PathVariable then it should lead to 4xx. Example: lookup by unique id.

Thus for the asked situation: "users/9" would be 4xx (possibly 404) But for "users?name=superman" should be 2xx (possibly 204)

According to w3 post,

> 200 OK

The request has succeeded. The information returned with the response is dependent on the method used in the request > 202 Accepted

The request has been accepted for processing, but the processing has not been completed. > > 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.

> 400 Bad Request

The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications > > 401 Unauthorized

The request requires user authentication. The response MUST include a WWW-Authenticate header field > > 404 Not Found

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent

What the existing answers do not elaborate on is that it makes a difference whether you use path parameters or query parameters.

• In case of path parameters, the parameter is part of the resource path. In case of /users/9, the response should be 404 because that resource was not found. /users/9 is the resource, and the result is unary, or an error, it doesn't exist. This is not a monad.
• In case of query parameters, the parameter is not part of the resource path. In case of /users?id=9, the response should be 204 because the resource /users was found but it could not return any data. The resource /users exists and the result is n-ary, it exists even if it is empty. If id is unique, this is a monad.

Whether to use path parameters or query parameters depends on the use case. I prefer path parameters for mandatory, normative, or identifying arguments and query parameters for optional, non-normative, or attributing arguments (like paging, collation locale and stuff). In a REST API, I would use /users/9 not /users?id=9 especially because of the possible nesting to get "child records" like /users/9/ssh-keys/0 to get the first public ssh key or /users/9/address/2 to get the third postal address.

I prefer using 404. Here's why:

• Calls for unary (1 result) and n-ary (n results) methods should not vary for no good reason. I like to have the same response codes if possible. The number of expected results is of course a difference, say, you expect the body to be an object (unary) or an array of objects (n-ary).
• For n-ary, I would return an array, and in case there are not results, I would not return no set (no document), I would return an empty set (empty document, like empty array in JSON or empty element in XML). That is, it's still 200 but with zero records. There's no reason to put this information on the wire other than in the body.
• 204 is like a void method. I would not use it for GET, only for POST, PUT, and DELETE. I make an exception in case of GET where the identifiers are query parameters not path parameters.
• Not finding the record is like NoSuchElementException, ArrayIndexOutOfBoundsException or something like that, caused by the client using an id that doesn't exist, so, it's a client error.
• From a code perspective, getting 204 means an additional branch in the code that could be avoided. It complicates client code, and in some cases it also complicates server code (depending on whether you use entity/model monads or plain entities/models; and I strongly recommend staying away from entity/model monads, it can lead to nasty bugs where because of the monad you think an operation is successful and return 200 or 204 when you should actually have returned something else).
• Client code is easier to write and understand if 2xx means the server did what the client requested, and 4xx means the server didn't do what the client requested and it's the client's fault. Not giving the client the record that the client requested by id is the client's fault, because the client requested an id that doesn't exist.

Last but not least: Consistency

• GET /users/9
• PUT /users/9 and DELETE /users/9

PUT /users/9 and DELETE /users/9 already have to return 204 in case of successful update or deletion. So what should they return in case user 9 didn't exist? It makes no sense having the same situation presented as different status codes depending on the HTTP method used.

Besides, not a normative, but a cultural reason: If 204 is used for GET /users/9 next thing that will happen in the project is that somebody thinks returning 204 is good for n-ary methods. And that complicates client code, because instead of just checking for 2xx and then decoding the body, the client now has to specifically check for 204 and in that case skip decoding the body. Bud what does the client do instead? Create an empty array? Why not have that on the wire, then? If the client creates the empty array, 204 is a form of stupid compression. If the client uses null instead, a whole different can of worms is opened.

It is sad that something so simple and well defined became "opinion based" in this thread.

A HTTP server only knows of "entities", which is an abstraction for any content, be it a static web page, a list of search results, a list of other entities, a json description of something, a media file, etc etc.

Each such entity is expected to be identifiable by a unique URL, e.g.

• /user/9 -- a single entity: a USER ID=9
• /users -- a single entity: a LIST of all users
• /media/x.mp3 -- a single entity: a media FILE called x.mp3
• /search -- a single entity: a dynamic CONTENT based on query params

If a server finds a resource by the given URL, it does not matter what its contents are -- 2G of data, null, {}, [] -- as long as it exists, it will be 200. But if such entity is not known to the server, it is EXPECTED to return 404 "Not Found".

One confusion seems to be from developers who think if the application has a handler for a certain path shape, it should not be an error. In the eyes of the HTTP protocol it does not matter what happened in the internals of the server (ie. whether the default router responded or a handler for a specific path shape), as long as there is no matching entity on the server to the requested URL (that requested MP3 file, webpage, user object etc), which would return valid contents (empty or otherwise), it must be 404 (or 410 etc).

Another point of confusion seems to be around "no data" and "no entity". The former is about content of an entity, and the latter about its existence.

Example 1:

• No data: /users returns 200 OK, body: [] because nobody registered yet
• No entity: /users returns 404 because there is no path /users

Example 2:

• No data: /user/9 returns return 200 OK, body: {}, because user ID=9 never entered his/her personal data
• No entity: /user/9 returns 404 because there is no user ID=9

Example 3:

• No data: /search?name=Joe returns 200 OK [], because there are no Joe's in the DB
• No entity: /search?name=Joe returns 404 because there is no path /search

After looking in question, you should not use 404 why?

Based on RFC 7231 the correct status code is 204

In the anwsers above I noticed 1 small missunderstanding:

1.- the resource is: /users

2.- /users/8 is not the resource, this is: the resource /users with route parameter 8, consumer maybe cannot notice it and does not know the difference, but publisher does and must know this!... so he must return an accurate response for consumers. period.

so:

Based on the RFC: 404 is incorrect because the resources /users is found, but the logic executed using the parameter 8 did not found any content to return as a response, so the correct answer is: 204

The main point here is: 404 not even the resource was found to process the internal logic

204 is a: I found the resource, the logic was executed but I did not found any data using your criteria given in the route parameter so I cant return anything to you. Im sorry, verify your criteria and call me again.

200: ok i found the resource, the logic was executed (even when Im not forced to return anything) take this and use it at your will.

205: (the best option of a GET response) I found the resource, the logic was executed, I have some content for you, use it well, oh by the way if your are going to share this in a view please refresh the view to display it.

Hope it helps.

Twitter uses 404 with a custom error message like "No data found".

Ref: https://developer.twitter.com/en/docs/basics/response-codes.html

TL;DR:

• If no user is found at /users/9, you should return a 404.
• If no user is found at /users?id=9, you should return a 204.

Long Version:

After reviewing my own usage of these status codes and the examples on this post, I would have to say that 404 is the appropriate response if User #9 was Not Found at the url of /users/9.

In my system today, our Application Insights logs are filled with hundreds of logged 404 errors that muddy up our logs all because we decided to return 404's when /users/9 had no correlating data. However, this does not mean our approach was incorrect when setting up our responses, rather, I would propose that it means our approach was incorrect when setting up our routing.

If you're expecting an endpoint to get a lot of traffic and are concerned about logging too many 404 errors, you should change your routing to fall in line with the status code you want, not force a status code to be inappropriately used.

We've since decided to make 2 changes to our code:

1. Change our route to work by expecting /users?id=9
2. Change our error code to 204 so that the 404's don't fill our AI logs.

At the end of the day, the architect of the API needs to understand how their API will be used and what kind of routing will be appropriate for that use case.

I believe that in the case of /users/9, the resource you are requesting is the user itself, User #9; you are asking the server to respond with an object identified as "9" that happens to exist in a path that has the word 'user' in it. If that object was not found, you should get a 404.

However, if you call /users?id=9, I feel that the resource you are requesting is the Users controller while also providing a bit more specificity so that it doesn't return a full list of all users. You are asking the server to respond with a specific user who can be identified by an ID number defined in the query string. Thusly, if no data was found, it makes sense to me that a 204 would be applicable because even if no data was found, the controller was.

The query string approach also accomplishes something that I think helps not only the API developers but also the client developers (especially junior developers or future developers who inherit this code, or code that makes calls to it):

It becomes immediately clear to anyone involved that 9 is an ID, not some arbitrary number. This point may seem moot in such a basic example, but consider a system that uses GUIDs as row ID's or allows you to get data by a person's name, or even a system that is returning info for specific ZIP/postal codes instead of row ID's. It would be useful for all developers involved if, at a glance, they knew whether that identifying parameter was a first, last, full name, or a ZIP/postal code instead of an ID.

I'd say, neither is really appropriate. As has been said – e.g. by @anneb, I, too, think that part of the problems arises from using an HTTP response code to transport a status relating to a RESTful service. Anything the REST service has to say about its own processing should be transported by means of REST specific codes.

1

I'd argue that, if the HTTP server finds any service that is ready to answer a request it was sent, it should not respond with an HTTP 404 – in the end, something was found by the server – unless told so explicitly by the service that processes the request.

Let's assume for a moment the following URL: http://example.com/service/return/test.

• Case A is that the server is “simply looking for the file on the file system“. If it is not present, 404 is correct. The same is true, if it asks some kind of service to deliver exactly this file and that service tells it that nothing of that name exists.
• In case B, the server does not work with “real” files but actually the request is processed by some other service – e.g. some kind of templating system. Here, the server cannot make any claim about the existence of the resource as it knows nothing about it (unless told by the service handling it).

Without any response from the service explicitly requiring a different behaviour, the HTTP server can only say 3 things:

• 503 if the service that is supposed to handle the request is not running or responding;
• 200 otherwise as the HTTP server can actually satisfy the request – no matter what the service will say later;
• 400 or 404 to indicate that there is no such service (as opposed to “exists but offline”) and nothing else was found.

2

To get back to the question at hand: I think the cleanest approach would be to not use an HTTP any response code at all other than said before. If the service is present and responding, the HTTP code should be 200. The response should contain the status the service returned in a separate header – here, the service can say

• REST:EMPTY e.g. if it was asked to search for sth. and that research returned empty;
• REST:NOT FOUND if it was asked specifically for sth. “ID-like” – be that a file name or a resource by ID or entry No. 24, etc. – and that specific resource was not found (usually, one specific resource was requested and not found);
• REST:INVALID if any part of the request it was sent is not recognized by the service.

(note that I prefixed these with “REST:” on purpose to mark the fact that while these may have the same values or wording as do HTTP response codes, they are sth. completely different)

3

Let's get back to the URL above and inspect case B where service indicates to the HTTP server that it does not handle this request itself but passes it on to SERVICE. HTTP only serves out what it is handed back by SERVICE, it does not know anything about the return/test portion as that is handeled by SERVICE. If that service is running, HTTP should return 200 as it did indeed find something to handle the request.

The status returned by SERVICE (and which, as said above, would like to see in a separate header) depends on what action is actually expected:

• if return/test asks for a specific resource: if it exists, return it with a status of REST:FOUND; if that resource does not exist, return REST:NOT FOUND; this could be extended to return REST:GONE if we know it once existed and will not return, and REST:MOVED if we know it has gone hollywood
• if return/test is considered a search or filter-like operation: if the result set is empty, return an empty set in the type requested and a status of REST:EMPTY; a set of results in the type requested and a status of REST:SUCCESS
• if return/test is not an operation recogized by SERVICE: return REST:ERROR if it is completely wrong (e.g. a typo like retrun/test), or REST:NOT IMPLEMENTED in case it is planned for later.

4

This distinction is a lot cleaner than mixing the two different things up. It will also make debugging easier and processing only slightly more complex, if at all.

• If an HTTP 404 is returned, the server tells me, “I have no idea what you're talking about”. While the REST portion of my request might be perectly okay, I'm looking for par'Mach in all the wrong places.
• On the other hand, HTTP 200 and REST:ERR tells me I got the service but did something wrong in my request to the service.
• From HTTP 200 and REST:EMPTY, I know that I did nothing wrong – right server, the server found the service, right request to the service – but the search result is empty.

Summary

The problem and discussion arises from the fact that HTTP response codes are being used to denote the state of a service whose results are served by HTTP, or to denote sth. that is not in the scope of the HTTP server itself. Due to this discrepancy, the question cannot be answered and all opinions are subject to a lot of discussion.

The state of a request processed by a service and not the HTTP server REALLY SHOULD NOT (RFC 6919) be given by an HTTP response code. The HTTP code SHOULD (RFC 2119) only contain information the HTTP server can give from its own scope: namely, whether the service was found to process the request or not.

Instead, a different way SHOULD be used to tell a consumer about the state of the request to the service that is actually processing the request. My proposal is to do so via a specific header. Ideally, both the name of the header and its contents follow a standard that makes it easy for consumers to work with theses responses.

According to the RFC7231 - page59(https://www.rfc-editor.org/rfc/rfc7231#page-59) the definition of 404 status code response is:

6.5.4. 404 Not Found 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. A 404 status code does not indicate whether this lack of representation is temporary or permanent; the 410 (Gone) status code is preferred over 404 if the origin server knows, presumably through some configurable means, that the condition is likely to be permanent. A 404 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [RFC7234]).

And the main thing that brings doubts is the definition of resource in the context above. According the same RFC(7231) the definition of resource is:

Resources: The target of an HTTP request is called a "resource". HTTP does not limit the nature of a resource; it merely defines an interface that might be used to interact with resources. Each resource is identified by a Uniform Resource Identifier (URI), as described in Section 2.7 of [RFC7230]. When a client constructs an HTTP/1.1 request message, it sends the target URI in one of various forms, as defined in (Section 5.3 of [RFC7230]). When a request is received, the server reconstructs an effective request URI for the target resource (Section 5.5 of [RFC7230]). One design goal of HTTP is to separate resource identification from request semantics, which is made possible by vesting the request semantics in the request method (Section 4) and a few request-modifying header fields (Section 5). If there is a conflict between the method semantics and any semantic implied by the URI itself, as described in Section 4.2.1, the method semantics take precedence.

So in my understand 404 status code should not be used on successful GET request with empty result.(example: a list with no result for specific filter)

Such things can be subjective and there are some interesting and various solid arguments on both sides. However [in my opinion] returning a 404 for missing data is not correct. Here's a simplified description to make this clear:

• Request: Can I have some data please?
• Resource (API endpoint): I'll get that request for you, here [sends a response of potential data]

Nothing broke, the endpoint was found, and the table and columns were found so the DB queried and data was "successfully" returned!

Now - whether that "successful response" has data or not does not matter, you asked for a response of "potential" data and that response with "potential" data was fulfilled. Null, empty etc is valid data.

200 just means whatever request we did was successful. I'm requesting data, nothing went wrong with HTTP/REST, and as data (albeit empty) was returned my "request for data" was successful.

Return a 200 and let the requester deal with empty data as each specific scenario warrants it!

Consider this example:

• Request: Query "infractions" table with user ID 1234
• Resource (API endpoint): Returns a response but data is empty

This data being empty is entirely valid. It means that user has no infractions. This is a 200 as it's all valid, as then I can do:

> You have no infractions, have a blueberry muffin!

If you deem this a 404 what are you stating? The user's infractions couldn't be found? Now, grammatically that is correct, but it's just not correct in REST world were the success or failure is about the request. The "infraction" data for this user could be found successfully, there are zero infractions - a real number representing a valid state.

---

[Cheeky note..]

In your title, you're subconsciously agreeing that 200 is the correct response:

> What is the proper REST response code for a valid request but an empty data?

---

Here are some things to consider when choosing which status code to use, regardless of subjectivity and tricky choices:

1. Consistency. If you use 404 for "no data" use it every time a response is returning no data.
2. Don't use the same status for more than one meaning. If you return 404 when a resource was not found (eg API end point does not exist etc) then don't also use it for no data returned. This just makes dealing with responses a pain.
3. Consider the context carefully. What is the "request"? What are you saying you are trying to achieve?

According to Microsoft: Controller action return types in ASP.NET Core web API, scroll down almost to the bottom, you find the following blurb about 404 relating to an object not found in the database. Here they suggest that a 404 is appropriate for Empty Data.

As stated by many, 404 is misleading and it doesn't allow the client to discriminate if the request uri doesn't exist, or if the requested uri cannot fetch the requested resource.

The 200 status is expected to contain resource data - so it is not the right choice. The 204 status means something else entirely and should not be used as response for GET requests.

All other existing status are not applicable, for one reason or the other.

I have seen this topic being discussed over and over in multiple places. For me, it is painfully obvious that to eliminate the confusion around the topic, a dedicated success status is needed. Something like "209 - No resource to display".

It will be a 2xx status because not finding an ID should not be considered a client error (if the clients knew everything which is in the server's DB, they would not need to ask anything to the server, wouldn't they?). This dedicated status will address all issues debated with using other statuses.

The only question is: how do I get RFC to accept this as a standard?

Just an addition from a developer that struggled many times with this situation. As you might have noticed it is always a discussion whether you return a 404 or 200 or 204 when a particular resource does not exist. The discussion above shows that this topic is pretty confusing and opinion based ( while there is a http-status-code standard existing ). I personally recommend, as it was not mentioned yet I guess, no matter how you decide DOCUMENT IT IN YOUR API-DEFINITION. Of course a client-side developer has in mind when he/she uses your particular "REST"- api to use his/her knowledge about Rest and expects that your api works this way. I guess you see the trap. Therefor I use a readme where I explicitly define in which cases I use which status code. This doesn't mean that I use some random definion. I always try to use the standard but to avoid such cases I document my usage. The client might think you are wrong in some specific cases but as it is documented, there is no need for additional discussions what saves time for you and the developer.

One sentence to the Ops question: 404 is a code that always comes in my mind when I think back about starting to develop backend-applications and I configured something wrong in my controller-route so that my Controller method is not called. With that in mind, I think if the request does reach your code in a Controller method, the client did a valid request and the request endpoint was found. So this is an indication not to use 404. If the db query returns not found, I return 200 but with an empty body.

According to w3, I believe in the following:

2xx:

> This class of status code indicates that the client's request was successfully received, understood, and accepted.

4xx:

> The 4xx class of status code is intended for cases in which the client seems to have erred.

If a client requests for /users, and it has users to list, the response code would be 200 OK (the client request was valid).

If a client requests for /users and it has no data, the response code would still be 200 OK.
The entity/resource being requested is a list of users, the list exists, just without any users in it (a 204 No Content could be used if an empty response is given, although I think an empty list [] would be better).
The client request was valid, and the resource does exist, so a 4xx response code wouldn't make sense here.

On the other hand, if a client requests for /users/9, and that user does not exist, the client made a mistake by asking for a resource that does not exist, a user. In this case, it makes sense to answer with a 404 Not Found.

The answers in this thread (26 at the time of writing) perfectly illustrate how important it is for a developer to understand the semantics of the constructs they are working with.

Without this understanding it may not be obvious that response status codes are properties of a response and nothing else. These codes exist in the context of the response and their meaning outside of this context is undefined.

The response itself is the result of the request. The request operates on resources. Resources, requests, responses, and status codes are the constructs of the HTTP, and as far as HTTP is concerned:

> HTTP provides a uniform interface for interacting with a resource (Section 2), regardless of its type, nature, or implementation, via the manipulation and transfer of representations (Section 3). Source.

In other words, the realm of the response status codes is limited by an interface which only cares about some target resources, and deals with messages used to interact with these resources. The server application logic is out of scope, the data you work with is also unimportant.

When HTTP is used it's always used with resources. The resources are ether transferred, or manipulated. In any case, unless we are in a quantum world, the resource either exists or it doesn't, there is no third state.

If an HTTP request is made to fetch (transfer) the representation of the resource (as in this question) and the resource doesn't exist, then the response result should indicate a failure with the corresponding 404 code. The objective - to fetch the representation - is not met, the resource was not found. There should be no other interpretation of the result in the context of the HTTP.

RFC 7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content, was referred to multiple times here, but mainly as a reference for status code description. I would highly recommend to read through the whole document, and not only section #6, to get a better understanding of the scope and semantics of the HTTP interface and its components.

Encode the response content with a common enum that allows the client to switch on it and fork logic accordingly. I'm not sure how your client would distinguish the difference between a "data not found" 404 and a "web resource not found" 404? You don;t want someone to browse to userZ/9 and have the client wonder off as if the request was valid but there was no data returned.

204 is more appropriate. Especially when you have a alert system to ensure you website is secure, 404 in this case would cause confusion because you don't know some 404 alerts is backend errors or normal requests but response empty.

What we have here is a tension between two paradigms.

In HTTP and REST, a URL identifies a resource, that user/9 resource includes the 9. HTTP should therefore return 404 - not found. This is the definition of RESTful. Later, you can PUT user/9, and then when you get then next time, you get the data. That's how HTTP and REST was designed.

An at HTTP level, if you didn't want a 404, a better URL would be user?id=9, then the user part would be found, and the function can do it's own processing and return it's own way of notifying "not found".

However, for convenience of specifying APIs, it's simply "much nicer" to use the user/9 format. This leaves us with the a dilemma: this request was made over HTTP, and the (opinionated) correct HTTP answer is 404; but through the lens of API consumers, the frameworks may not handle the 404 well, and they want a 200 + a "not found" payload (204 may also be problematic for many frameworks).

This layering an API on top of an already defined protocol (HTTP) is what has caused the tension. There's no problem when designed as a truely RESTful API (and correctly handling the 404's that that would produce).

If you believe that user/9 should return 200 + "not found", then you're using user as an RPC end point and then encoding parameters in the rest of the URL. I would suggest that this is poor design, contrary to a RESTful specification, and also totally understand how we got here.

If you control both ends - do what works, given the constraints of your server and - more likely - you client-side frameworks.

(Think of the consequences of doing a HEAD request on user/9 - you don't get to supply any content in the response. A 200 would indicate that user/9 does indeed exist, where as 404 would (correctly) indicate it's absence.)

Why not use 410? It suggests the requested resource no longer exists and the client is expected to never make a request for that resource, in your case users/9.

You can find more details about 410 here: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

404 would be very confusing for any client if you return just because there is no data in response.

For me, Response Code 200 with an empty body is sufficient enough to understand that everything is perfect but there is no data matching the requirements.

In this scenario Ruby on Rails responses with 404 Not Found.

Client requested for a resource that does not exist. So, 404 Not Found is more appropriate.

---

Edit

I see that, in this scenario, many developer do not like 404 not found.

If you do not want to use 404, I think, you can use any of these two response codes:

• 200 OK
• 204 No Content

If you use 200 OK : response body should be empty json :[] or {}

If you use 204 OK : response body should be empty.

I dont think 404 is correct response.

If you use 404, how do you know it is that the api was not found or that the record in your database was not found?

From your description, I would use 200 OK since your api executed all logic without ANY issue. It just could not find the record in database. So, it is not API issue, nor database issue, it is your issue, you are thinking that the record exist but it does not. For that reason, API executed successfully, database query executed successfully, but nothing was found to return.

For that reason, in case like this, I would use

200 OK

with empty response like [] for arrays or {} for objects.