Sam Ruby and Leonard Richardson are writing a book on REST Web services. Very exciting. I love reading Sam’s blog and watching him untangle standards.
Looking at the Table of Contents, I’m particularly interested in “Appendix A: HTTP status codes and when to use each one.” (Yes, I am serious.)
When I designed “Dude, Where’s My Used Car,” my mashup between eBay Motors and Google Maps, I churned through a number of different ways to signal failure. My biggest issue is that there’s so many places my request can fail, I’m not sure how to “correctly” represent that back inside my mashup.
For example, in response to a user-generated action (such as filling out a form and clicking submit), my mashup initiates a HTTP GET AJAX request (well, AJAJ because I’m using JSON instead of XML) which hits my web server. I then use PHP to parse the request, generate a corresponding SOAP request to eBay’s web service gateway, wait for result, pick it apart and convert the bits I want to JSON. This data is then passed back to the browser, where I (well, Dojo, actually) evals it.
When everything works, everything works.
But what happens when the user enters an invalid ZIP Code? eBay will return an error, and I’d like to proxy this back to the application, so I can toss up a message.
Should I return 200 OK and pass back the message? That’s one option, but I’d prefer not to need to check the data structure to see if I got the normal data I expected or some nasty error instead.
Besides, Dojo lets me specify a separate error handler callback function. It seems a cleaner design to handle all the errors there. But then I can’t return 200. What to use instead? 400 Bad Request?
Then there’s cases where the error is not the user’s fault, but either my fault or eBay’s fault. What should I do if eBay returns a SOAP envelope my PHP script can’t parse? 502 Bad Gateway? Or if the eBay server returns a SOAP Fault? The same 500 Internal Server Error I got back from eBay?
Should I not let my web server’s interaction with eBay bleed back into browser?
Here’s another example: when eBay’s server is too busy, it returns Error Code 10007. I can retry (and hopefully fix the problem) inside of my PHP script without even needing to message back to the browser. But if I did ultimately give up retrying, should I pass back 503 Service Unavailable? Am I on the hook for translating between SOAP and REST in my server-side proxy PHP script?
Maybe I can use 4xx codes for problems which are “user generated” in some form. These are things which require the user to take an action to remedy. And for things which are broken but otherwise outside of the control of the user (such as my SOAP client being unable to understand eBay’s SOAP response) I can use 5xx.
I actually like this idea, but I’m wondering if there’s a “standard” way to indicate errors and failures in a AJAX application. I can’t find one, but I’m not very familiar with what’s out there.
PS: My vote is to leave off the “With Ruby” part of the title, and go with plain “REST Web Services”.