i'm constructing a web-service that is used, in this particular case, to ask for information about a patron.
Let's say, for the sake of argument, that the lookup web hit is:
GET /patrons/619 HTTP/1.1
If the patron is found, i return code 200:
HTTP/1.1 200 OK
If you omit, or give an account number that is not a number, i return 400. For example the following bad requests:
GET /patrons HTTP/1.1 GET /patrons/ HTTP/1.1 GET /patrons/G619 HTTP/1.1 GET /patrons/kirsten%20guyer HTTP/1.1
all return error 400 (Bad Request), e.g.:
HTTP/1.1 400 Invalid patron number
i want to have a status code for patron not found, returned as the HTTP status code. For example:
GET /patrons/1322 HTTP/1.1 HTTP/1.1 404 Not Found
i've thought about using 404 (Not Found), which is a valid response (the requested resource was, really and truely, not found.) But i'm afraid people debugging it might think that it means that they spelled
Can anyone think of another http status code i could use?
Update: i'm eyeballing
204 No Content The server successfully processed the request, but is not returning any content.
What say you?
Don't forget, that not all HTTP servers serve up HTML content. If an IIS web-server is asked for a resource called:
GET /MyStartPage.html HTTP/1.1
Then the HTTP server has to decide what to respond with. On most web-servers, a resource named /MyStartPage.html corresponds to a file sitting on the hard drive.
Whereas StackOverflow does:
GET /posts/1027301 HTTP/1.1
Which, if that resource doesn't exist, the web-server should (rightly) return 404.
Processing chunked encoded HTTP POST requests in python (or generic CGI under apache)
Python POST ordered params
Is there a tutorial for inserting messages into MSMQ 3.0 using PHP over HTTP?
Also, there's very little you're going to be able to do to counter human behavior anyway (thinking one thing when it's really another).
Compatibility of Comet with current technology
If you're returning a little error msg as part of the error code, everything should work out.
How often is the Silverlight Access policy accessed?
You could even suggest to them a possible fix..
Returning a bare JSON-string
Returning a 500 when the application is doing exactly what it's designed to do also seems a little odd.
Adobe air http auth
404 describes exactly the situation: Resource not found..
HTML Form works with GET but not with POST
Developers of the API will understand what 404 means and will therefore follow there own usual debugging process in order to resolve the problem.
Stick to the protocol..
You could always have a custom error document that explains that it is the Patron ID that is not found.. A 400 error implies that the client sent malformed syntax, which is not the case in your example.
Thus, you should not use this error code.
It may seem that "Bad Request" is accurate, but what this actually means is there's an error in the request header syntax.. This is also not a 500 error because no error has occurred.
There is no problem with the web server fulfilling the request, the fact is that the request is seeking a resource that is not present.. 404 is the only appropriate response, unless you want to consider it a fully valid request, return status 200 and a page explaining that the requested Patron does not exist.. From my original comment on the question:.
I don't think that a 200-level error would be appropriate either, consider the explanations at W3 w3.org/Protocols/rfc2616/rfc2616-sec10.html.
It's at the application level.
One possible solution is to use the Null Object Pattern to return a null 'Patron' that conforms to the Patron interface, but indicates that no such person exists..
. UPDATE: I've been convinced that this answer is wrong.
However, I want to leave it up, as it is a potentially valid answer (depending on details not presented in the question), and I think the comments are instructive.
They separate a transport level (HTTP) from the messages exchanged (XML).
A 404 error (which is on the transport level) is returned only, if you request a non-existing API endpoint (wrong URL).. With a REST webservice however, you use HTTP methods and statuses directly for message exchange.
REST uses different HTTP methods (GET/POST/PUT/DELETE) to specify which action is wanted and the server returns the status as the HTTP status.
So in case of a REST webservice, 404 would be the proper HTTP status if a patron could not be found.. 500 is inappropriate in any case I think, since 5xx means that there's been something wrong on the serverside (which isn't the case) while 4xx errors mean that there's something wrong on the client side..
For APIs which are to be used by both borwsers and native apps, I find it is much simpler to use the HTTP codes for status indication.
And if necessary use a couple of extra codes from the unallocated ones for conditions that don't have a good fit to existing HTTP codes..
The returned document should contain an error code that is part of a documented set of codes specific to your web service, as well as a short description of the problem and optionally a more detailed description of the problem..
In this case then, you'd return 200 as normal with the payload of your request (XML or JSON or whatever) indicating that no matching entity was found. I'd consider non-200 error codes similar to exceptions in conventional programming languages, and the HTTP response body more like the return code.
Imagine if you were implementing this conventionally - would you throw an exception if no entity was found, or return
null? Personally, given the fragile nature of network connections, I would want to reserve all HTTP-level error codes for problems in communication, and I'd much rather always return
200 OKfrom the service itself, along with a payload specifying the result or any service-level error..