[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: REST API questions


Nelson Minar wrote:
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)
  ...


In a REST form of the API you would see something
different, on a case by case basis you get:

>   Wrong password
Return HTTP status code 401/403

> Blog does not exist
Return 404 since that URI identifies the blog, or more appropriately 410 if they got Jon Robb'd.

>   User over quota
Could be either 413 or 500

>   Post with that ID already exists
This can not happen in the REST form of the API.

> Post with that ID does not exist (on delete)
This is not an error in the REST form of the API. Each entry has it's own URI and DELETEing a resource returns a 200 on success whether the resource existed at the time or not.



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.


Kind of a red-herring since in the REST form of the API these problems don't exist. Even if there could be an error, the client that made the request knows which entry it was trying to delete, given that the client probably got the URI from the search interface, it already has the title of the entry to display to the user.


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".


Yes, 404 would be an abuse if you used POST to update entries, but if
you used PUT and the entry was uniquely identified by its URI then it would be perfectly appropriate to use 404 or 410.


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


You are right that the specification at this time does not cover error codes. In general the HTTP Status code should be the first line of defense, such as 403 Not Authorized, etc. There are errors that will need more detail than just the status code, and I see three possibilities:

1. Do nothing. That is, let the server decide the error code and formatting to return it in. For example, when you get a 404 on a web-site you often get an HTML page or a text/plain document. Not my favorite option.

2. Mandate a text/plain result that describes the problem.

3. The third option is to define an XML format for describing errors, e.g.

<error>
   <title></title>
   <description></description>
</error>


	Thanks,
	-joe

--
http://BitWorking.org
http://WellFormedWeb.org