Question

I’m trying to determine the best practice in a REST API for determining whether the client can access a particular resource. Two quick example scenarios:

A phone directory lookup service. Client looks up a phone number by accessing eg.
GET http://host/directoryEntries/numbers/12345
… where 12345 is the phone number to try and find in the directory. If it exists, it would return information like the name and address of the person whose phone number it is.

A video format shifting service. Client submits a video in one format to eg.
POST http://host/videos/
… and receives a ‘video GUID’ which has been generated by the server for this video. Client then checks eg.
GET http://host/videos/[GUID]/flv
… to get the video, converted into the FLV format, if the converted version exists.

You’ll notice that in both cases above, I didn’t mention what should happen if the resource being checked for doesn’t exist. That’s my question here. I’ve read in various other places that the proper RESTful way for the client to check whether the resource exists here is to call HEAD (or maybe GET) on the resource, and if the resource doesn’t exist, it should expect a 404 response. This would be fine, except that a 404 response is widely considered an ‘error’; the HTTP/1.1 spec states that the 4xx class of status code is intended for cases in which the client ‘seems to have erred’. But wait; in these examples, the client has surely not erred. It expects that it may get back a 404 (or others; maybe a 403 if it’s not authorized to access this resource), and it has made no mistake whatsoever in requesting the resource. The 404 isn’t intended to indicate an ‘error condition’, it is merely information – ‘this does not exist’.

And browsers behave, as the HTTP spec suggests, as if the 404 response is a genuine error. Both Google Chrome and Firebug’s console spew out a big red "404 Not Found" error message into the Javascript console each time a 404 is received by an XHR request, regardless of whether it was handled by an error handler or not, and there is no way to disable it. This isn’t a problem for the user, as they don’t see the console, but as a developer I don’t want to see a bunch of 404 (or 403, etc.) errors in my JS console when I know perfectly well that they aren’t errors, but information being handled by my Javascript code. It’s line noise. In the second example I gave, it’s line noise to the extreme, because the client is likely to be polling the server for that /flv as it may take a while to compile and the client wants to display ‘not compiled yet’ until it gets a non-404. There may be a 404 error appearing in the JS console every second or two.

So, is this the best or most proper way we have with REST to check for the existence of a resource? How do we get around the line noise in the JS console? It may well be suggested that, in my second example, a different URI could be queried to check the status of the compilation, like:
GET http://host/videos/[GUID]/compileStatus
… however, this seems to violate the REST principle a little, to me; you’re not using HTTP to its full and paying attention to the HTTP headers, but instead creating your own protocol whereby you return information in the body telling you what you want to know instead, and always return an HTTP 200 to shut the browser up. This was a major criticism of SOAP – it tries to ‘get around’ HTTP rather than use it to its full. By this principle, why does one ever need to return a 404 status code? You could always return a 200 – of course, the 200 is indicating that the a resource’s status information is available, and the status information tells you what you really wanted to know – the resource was not found. Surely the RESTful way should be to return a 404 status code.

This mechanism seems even more contrived if we apply it to the first of my above examples; the client would perhaps query:
GET http://host/directoryEntries/numberStatuses/12345
… and of course receive a 200; the number 12345‘s status information exists, and tells you… that the number is not found in the directory. This would mean that ANY number queried would be ‘200 OK’, even though it may not exist – does this seem like a good REST interface?

Am I missing something? Is there a better way to determine whether a resource exists RESTfully, or should HTTP perhaps be updated to indicate that non-2xx status codes should not necessarily be considered ‘errors’, and are just information? Should browsers be able to be configured so that they don’t always output non-2xx status responses as ‘errors’ in the JS console?

PS. If you read this far, thanks. 😉

Answer 1

I think you have changed the semantics of the request.
With a RESTful architecture, you are requesting a resource. Therefore requesting a resource that does not exist or not found is considered an error.

I use:

• 404 if GET http://host/directoryEntries/numbers/12345 does not exist.

• 400 is actually a bad request 400 Bad Request

Perhaps, in your case you could think about searching instead.
Searches are done with query parameters on a collection of resources

What you want is
GET http://host/directoryEntries/numbers?id=1234
Which would return 200 and an empty list if none exist or a list of matches.