When in doubt, consult the documentation. Reviewing the W3C definitions for HTTP Status codes, gives us this:
200 OK - The request has succeeded. The information returned with the response is dependent on the method used in the request.
404 Not Found - The server has not found anything matching the Request-URI.
In the context of your API, it very much depends on how queries are created and how objects are retrieved. But, my interpretation has always been that:
- If I ask for a particular object, and it exists return
200
code, if it doesn't exist return the correct 404
code.
- But, if I ask for a set of objects that match a query, a null set is a valid response and I want that returned with a
200
code. The rationale for this is that the query was valid, it succeeded and the query returned nothing.
So in this case you are correct, the service isn't searching for "a specific thing" it is requesting a particular thing, if that thing isn't found say that clearly.
I think Wikipedia puts it best:
200 OK - ... The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource.
404 Not Found - The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
Seems pretty clear to me.
Regarding the example requests
/GoalTree/GetByDate?versionDate=...
/GoalTree/GetById?versionId=...
For the format, you said, you always return the nearest revision to that date. It will never not return an object, so it should always be returning 200 OK
. Even if this were able to take a date range, and the logic were to return all objects within that timeframe returning 200 OK - 0 Results is ok, as that is what the request was for - the set of things that met that criteria.
However, the latter is different as you are asking for a specific object, presumably unique, with that identity. Returning 200 OK
in this case is wrong as the requested resource doesn't exist and is not found.
Regarding choosing status codes
- 2xx codes Tell a User Agent (UA) that it did the right thing, the request worked. It can keep doing this in the future.
- 3xx codes Tell a UA what you asked probably used to work, but that thing is now elsewhere. In future the UA might consider just going to the redirect.
- 4xx codes Tell a UA it did something wrong, the request it constructed isn't proper and shouldn't try it again, without at least some modification.
- 5xx codes Tell a UA the server is broken somehow. But hey that query could work in the future, so there is no reason not to try it again. (except for 501, which is more of a 400 issue).
You mentioned in a comment using a 5xx code, but your system is working. It was asked a query that doesn't work and needs to communicate that to the UA. No matter how you slice it, this is 4xx territory.
Consider an alien querying our solar system
Alien: Computer, please tell me all planets that humans inhabit.
Computer: 1 result found. Earth
Alien: Computer, please tell me about Earth.
Computer: Earth - Mostly Harmless.
Alien: Computer, please tell me about all planets humans inhabit, outside the asteroid belt.
Computer: 0 results found.
Alien: Computer, please destroy Earth.
Computer: 200 OK.
Alien: Computer, please tell me about Earth.
Computer: 404 - Not Found
Alien: Computer, please tell me all planets that humans inhabit.
Computer: 0 results found.
Alien: Victory for the mighty Irken Empire!
Regarding PUT, but applies to POST as well. The HTTP specification section 9 is a little empty on rules or even advice (SHOULD) when it comes to the scenario that you are describing. The line relevant to your question is most closely covered by:
If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response. If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.
I do not think I would lose any sleep over it, but I would ask, what do you gain by adding the chunk of JSON into the response? You've just bulked out (OK, bulked might be overkill!) the response repeating less accurately what the status code should already have told you. If your PUT resulted in a new object return 201 (as is the intention of PUT), if it updated an object return 204.
Incidentally, API aside, instead of 200, if you don't return anything use 204.
Assuming that you are developing a set of RESTful interfaces, there is no standard per se, so whatever you do, document it well,, provide examples and everything will be alright.
Best Answer
In principle the first part is right, but "file" is ambiguous. You're mistaken about what "file" means here, or more generally in the context of RESTful web services.
A web service exposes a resource to the user via HTTP. If the client tries to
GET
a resource—via AJAX or not—and the requested resource is not there, then the server should raise a 404 error. The resource is not the actual file stored on the server (e.g.ajax.php
or some CGI script), but the resource the client tries to access, be it an image, or just textual content.Wikipedia also mentions:
Another example from A. Rodriguez, "Restful web services: The basics." IBM developerWorks (2008):
The AJAX submitting app should handle the case where the connection to the server times out or an internal server error (5xx) is thrown, but it should also just be able to deal with the fact that the resource it tried to fetch (e.g. a user, an image record, etc.) isn't there at this point in time.
Of course, this is all focused on RESTful approaches. You don't have to follow this, but it would make sense to leverage the semantics of HTTP status codes as much as possible, especially in the way the developer here did it—by adding specific error messages in the response body. The other approach of delivering a quasi-standard response with a
success
flag and a message is also fine, but it requires stronger coupling of front- and backend applications.