[gcs-pcs-list] concerns about the heavy use of http response codes
in unAPI
Raymond Yee
yee at berkeley.edu
Fri Mar 10 11:05:33 EST 2006
Hi everyone,
I've been pondering one thing that has nagged me about unAPI: the use
of http response codes in unAPI. Even though the proposed usage seems
to be very much in the spirit (and law) of the http protocol, it was
nonetheless unfamiliar to me. I've spent a lot of time looking at
various web services APIs and from what I could recall, they largely
tended to shy away from heavy use of http response codes and largely
reported status and errors in custom XML messages.
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. By looking at is recorded at the site, I see the
following use of "HTTP response codes are explicitly used by this
protocol. Note that this does not include 'ordinary' HTTP responses,
such as a normal 404, with no API-specific meaning":
blogger: 401, 204
blogmarks: 401, 404, 500 (with details in XML body)
delicious: 503
hotornot: 401
MSN spaces: 400, 403
Plaxo: 205, 211, 400, 401, other 400 and 500 level codes
Raw Sugar: 401, 404, 501, 503 (throttled)
upcoming.org: 403, 404
Yahoo image search/local search/: 400, 403, 503
I also looked for sites that use XML-based error reporting. I've not
compiled a nice list yet, but found at least the following:
backpack
in XML with error codes
[http://www.backpackit.com/api/ Backpack API: Build your own apps on
Backpack]
blogmarks
[http://dev.blogmarks.net/wiki/AtomApiSpec AtomApiSpec -
Blogmarks.net - Trac]: "Server returning a 4xx or 5xx HTTP code means
that an error occured while processing the request. If so, response body
describes the error as XML."
box.net
[http://dev.box.net/api-documentation Box.net :: API Documentation]
"Custom XML response"
easyutil
in XML
http://www.easyutil.com/rec_api_ref.html
EVDB
in XML
[http://api.evdb.com/docs/errors EVDB API - /events/new]
feedburner
error in XML
e.g.,
[http://api.feedburner.com/awareness/1.0/GetFeedData?uri=burnthisRSS2x ]
geocoder.ca
error code in XML
[http://geocoder.ca/?api=1 geocoder.ca: a free Canadian address
geocoder]
Flickr
[http://www.flickr.com/services/api/response.rest.html Flickr Services]
<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="fail">
<err code="[error-code]" msg="[error-message]" />
</rsp>
hotornot
[http://dev.hotornot.com/wiki/ErrorCodes ErrorCodes - HOTorNOT
Developer Site] 401 User is not authorized for this method
onlywire
in XML [http://www.onlywire.com/index?api OnlyWire: The Only
BookMarklet You'll Ever Need!]
openomy.com
in XML
[http://documentation.openomy.com/index.php/How_Web_Apps_Work#Failure
How Web Apps Work - OpenomyDocumentation]
pixagogo
in XML
[http://www.pixagogo.com/tools/api/apihelp.aspx?p=data#error
Pixagogo - API Help Pixagogo]
prodigem
in XML
[http://torrentocracy.com/mediawiki/index.php/Prodigem_API_REST_Errors
Prodigem API REST Errors - TorrentocracyWiki]
shadows
just like delicious
[http://www.shadows.com/features/site/help/api.htm Shadows - Tag,
comment, and rate your favorite web pages.]: Errors are reported using
standard HTTP error codes.
simpy
in XML
[http://www.simpy.com/simpy/service/api/rest/Status.jsp Simpy
Services: REST API : Status]
syndic8
xml-rpc error codes
What do I see:
* there is some usage of http response codes
* I think there is still greater usage of xml error codes. I think a
lot about how Flickr works -- and it doesn't use http response codes to
report status. Neither do a lot of web services.
* Yahoo uses both
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 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.
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. In this
iteration of the spec we'd like to be reasonably thorough in testing the
pattern with a variety of popular tools to see how easily this response
pattern can be implemented. So please block off a few hours in the next
few weeks to try it out with your own favorite toolchain.
I've not looked at a broad range of tools -- but I can say in Python's
urllib2 library (the one an Mark Pilgrim identified as a good way to do
http) will throw an HTTPError exception on receipt of the 300 code.
According to http://diveintopython.org/http_web_services/etags.html:
urllib2 also raises an HTTPError exception for conditions that you
would think of as errors, such as 404 (page not found). In fact, it will
raise HTTPError for any status code other than 200 (OK), 301 (permanent
redirect), or 302 (temporary redirect). It would be more helpful for
your purposes to capture the status code and simply return it, without
throwing an exception. To do that, you'll need to define a custom URL
handler.
Not an insurmountable barrier by any means -- but something that might
throw developers for a loop. This type of behavior might be similar to
those in other libraries.....
I'll end with other links that I found helpful:
* [http://www.oreillynet.com/pub/wlg/4009 RESTful Error Handling] --
the article + the disagreeing comments
* [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP/1.1:
Status Code Definitions]
*
http://cipolo.med.yale.edu/pipermail/gcs-pcs-list/2006-March/000499.html
-- Eric Hellman's comment on 300
*
[http://diveintomark.org/archives/2003/07/21/atom_aggregator_behavior_http_level
Atom aggregator behavior (HTTP level) [dive into mark]] -- Mark Pilgrim
on use of http codes in building an atom aggregator
-Raymond
--
--
Raymond Yee 2195 Hearst (250-22)
Technology Architect UC Berkeley
Interactive University Project Berkeley, CA 94720-3810
yee at uclink.berkeley.edu 510-642-0476 (work)
http://iu.berkeley.edu/rdhyee 413-541-5683 (fax)
-------------- 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/20060310/18028ef6/smime.bin
More information about the gcs-pcs-list
mailing list