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

[Raymond Yee]

Hi Leigh,

Hey, thanks for responding. 

Leigh Dodds wrote:
> 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.
I see that you did a similar analysis to me-- one that is more in depth 
and focused on some particular apps.  It's nice to know that we're 
thinking similarly about this topic.  Thanks also for the reference to 
your article.  I enjoyed reading it a lot and found it very helpful.  
I've since assigned it to my class on information remix and will be 
discussing it in class tomorrow.
>
> 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.
Yes, you're certainly right that the use of HTTP status codes and XML 
documents are not mutually exclusive.  I didn't mean to imply that.  I 
don't believe that they are orthogonal though -- in the sense that there 
is not some practical interdependence.  For instance, when I use 
Flickr's API, I've been trained to expect error handling to do done only 
at the XML "layer" and not to get error codes from the http response 
codes -- unless the transport of the XML is badly amiss.  This 
expectation comes from not thinking of http as an *application protocol* 
as you point out below -- but more as a *transport layer*. 
>
> 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.
It's too bad that a lot of sites mimic Flickr's "design pattern".  We 
just need to be aware that there needs to be some sort of unlearning 
involved for developers who learn by studying things like 
Flickr.....(and I include myself in that camp!)
>
> 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.
On this point, I've been reading Jon Udell: 

* http://www.infoworld.com/article/05/09/12/37FEsoaevolve_1.html
* http://www.infoworld.com/article/06/01/11/73703_03OPstrategic_1.html
* http://www.infoworld.com/article/06/03/08/76065_11OPstrategic_1.html

Though I really appreciate the elegance and simplicity of REST, I do 
think that there is a role for SOAP and the whole WS-* stack.  Not so 
much in my work -- but in a lot of enterprise application.  Even for 
things like Flickr, I'd love for some type of WSDL-equivalent for REST 
-- where I could just feed a wsdl file to my client and be able to wire 
Flickr into my application w/o having to read the spec and do a lot more 
manual integration.   It's interesting that Flickr has introspection 
methods:  .e.g, 
http://www.flickr.com/services/api/flickr.reflection.getMethods.html  
Makes one wonder whether one could cook up some WSDL-equiv for Flickr here.

-Raymond

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 3166 bytes
Desc: S/MIME Cryptographic Signature
Url : http://cipolo.med.yale.edu/pipermail/gcs-pcs-list/attachments/20060314/0e058ddb/smime.bin