[gcs-pcs-list] concerns about the heavy use of http response codes in unAPI

[Leigh Dodds]

Hi Raymond,

> To test my suspicions, I spent some time going through the 170+ APIs 
> recorded at http://www.programmableweb.com/apis, looking for uses of 
> http response codes.   

Very thorough job! I looked at this and other aspects of protocol design
in "social content services" in a paper I wrote last year:

http://www.idealliance.org/proceedings/xtech05/papers/02-07-04/

See the sections entitled "use of status codes" for a similar breakdown
of code usage, and some analysis of the various practices.

The use of HTTP status codes and XML documents to indicate errors is
not actually mutually exclusive. In fact they're orthogonal. Where an
HTTP response can have a body, it's generally the case that APIs return
XML in some format.

E.g. an unAPI implementation might return an 500 error with an XML
document containing a specific error message and possibly further 
details including an application specific error code.

A lot of sites mimic Flickr which uses 200 almost exclusively. This is a 
Bad Idea. A key reason to use HTTP response codes is that web 
intermediaries (e.g. caching proxies) and other generic web clients 
(e.g. a browser or web crawler) will have some understanding of the
semantics of the response: it's an error; it's a (permanent) redirect;
everything worked fine. This is almost as important as correctly
using HTTP request methods.

The response codes licence in intermediaries to apply generic processing 
to API responses. E.g. caching the data. The ability to do this is a key
aspect of the REST architecture and is an important aspect of enabling
scaling of distributed systems to the level of the 'net.

If an API returns a 200 OK response for all interactions then clients
must understand the specific XML formats of that service in order to
interpret the message.

> It was later in the day that it occurred to me that maybe I've been 
> seeing unAPI from a conceptual frame that is not that of unAPI:  unAPI 
> isn't really cast as an XML over HTTP web service protocol but a 
> HTTP-centric protocol with happens to spit out XML on occassions.  Also, 
> after looking briefly at the Atom Publishing Protocol, which strikes me 
> as avowedly RESTful and therefore heavily into using the ins and outs of 
> http, I'm starting to understand the logic of the http response codes.  

I'm not sure I see the difference. An important thing to grok is that
HTTP is an *application protocol*. It's not a transport protocol or 
something to be abstracted away. It has clear, generic semantics that 
apply to almost all applications: it worked; please try later; you need
to authenticate; there was an error, etc.

Understanding that this is the role that HTTP plays in web architecture
means that you can design applications and APIs that get the most out of
that architecture (e.g. caching, proxying). It also makes it easier to
write generic client toolkits (e.g. browsers, curl, wget) that can
usefully interact with services that properly integrate with HTTP.

Consider the fact that most HTTP clients will helpfully follow 3XX
redirects from a server and do a GET to retrieve the indicated resource.
If you were serving responses as a 200, you'd have to define a custom
message in your protocol in order to indicate when a client may have to
consult some other resource, and all client developers would need to
implement support for your bespoke mechanism. With HTTP some things come 
for "free".

> I do wonder, however, whether this logic will be foreign to our target 
> audience of developers though -- that's one concern I have.  I learned a 
> lot about http response codes the last few days because I wanted to 
> understand unAPI.  I suspect that there are a lot of people out there 
> who don't know that much about http (even if they should to be a 
> self-respecting web developer) and who won't invest the effort to learn 
> to implement unAPI.

I think what we're seeing in the move to simpler, RESTful protocols and 
a rejection of SOAP and WS-* services is that these add unnecessarily
complex layers on top of HTTP.

So I agree that there's a slightly different mindset, but I think the 
requisite shift is already underway and that developers are climbing the 
learning curve of how to get the most of out existing web architecture.

> Another concern I have is technical.  Dan Chudnov wrote 
> (http://cipolo.med.yale.edu/pipermail/gcs-pcs-list/2006-March/000499.html):
> 
>   Probably the biggest issue we agreed to track carefully is browser 
> /language/framework support for 300 Multiple Choices response. 

One for a separate thread. I wanted to raise this as an issue also, as I 
think in this case a 200 response is more suitable. (I'd also like to
see the response include explicit links to the alternate format 
documents, but will raise that separately also).

Cheers,

L.
--