REST API questions

[Nelson Minar <nelson@xxxxxxxxxx>]

Hi there, I'm kibbitzing on the Atom/Echo/nEcho/Pie design. I work at
Google and keep a blog, but I'm not really part of the Blogger crew.
(I have worked on the Google Web APIs, a SOAP interface). 

I read Joe's excellent draft of a REST proposal and had a bunch of
questions for him. We thought it'd be productive to discuss these
questions here on the list.


One thing Joe's current draft doesn't talk much about is error
signaling. It's easy to design and use an API when there are no
errors. It's harder to handle error cases correctly, but it is very
important.

Some potential errors in a POST API:
  Wrong password
  Blog does not exist
  User over quota
  Post with that ID already exists
  Post with that ID does not exist (on delete)
  ...

Errors are mostly just strings, but some of the error data should be
structured. For instance, with "ID does not exist" it'd be nice to
send back the ID as well.

For SOAP, in general SOAP's fault handling is not great but it gets
the job done. SOAP uses a <soap:fault> element to signal an error,
inside a SOAP envelope and body. The fault has some sub elements -
faultcode, faultstring, detail, etc. The HTTP binding specifies that
faults also throw an HTTP 500 status code.
  http://www.w3.org/TR/SOAP/#_Toc478383507

I don't think Joe's API proposal covers errors yet. Would errors in a
REST API be signaled in HTTP response codes with an XML document in
the body of the response to provide detail? Do different HTTP status
codes mean different things? I could imagine using 403 Not Authorized
for authentication failures. But I think you'd need 500s for most
other things; it'd be an abuse of 404 to signal "post with that ID
does not exist".

And what about non-HTTP transports? What would faults look like in a
REST-like API when you're using some other transport?