Well REST-ed

So Matt and I were talking about routing, REST and resources yesterday. At StirTrek this spring Mike Amundsen gave a talk entitled: Programming the Cloud with HTTP/REST. Three of the things I took away from there were:

  • Reconsider the links were propagating. What has to do with the resource one is requesting? What is metadata pertinent to the request? Route accordingly.
  • People have forgotten that perfectly valid http responses are being treated as something they are not. A 404 represents a valid response for a resource that is not on this server. It isn’t an error. Don’t treat it as one.
  • Go read Fielding’s Architectural Styles and the Design of Network-based Software Architectures. Seriously.

Steve Klabnik has two good recent and relevant articles here and here as well.

Anyway, two points came out of our conversation that I wanted to highlight:

APIs can be painful to write. You want to follow the best practices and do things the right way, but the technical ability of your users is the wildcard you can never know beforehand. Matt’s said that credentials should be in the request header, and I think he is spot-on correct. However, I am not sure that all users will know how to do this and instead will want to see it in a querystring value.

We both agreed that it has nothing to do with the resource and should stay out of the route (url).

The second point was that if you were looking up an address like:

/address/list/1060 West Addison Street/Chicago/IL/60068

and I didn’t have a record for that address, what is the correct response?

If you answered 404, well done. I don’t have that address, it is not here:

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent. The 410 (Gone) status code SHOULD be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable. -rfc2616 w3c

If you answered that this is an address from The Blues Brothers, then you’re on another level entirely.

In an age where people want to cover up “not found” with custom error pages and such, we’ve forgotten that 404 is a perfectly valid response to a request. It isn’t an error, and it shouldn’t be treated as such. I’ve never met one of those 404 pages that did anything for me anyway; a 404 custom error page is an entire waste of bandwidth.

Have a polling application over http? A 404 response gets picked up in the headers far faster than looking for content that says “that’s not here”.

If you’re just looking for something to be there or not, you don’t even need content to tell you what the header already does.