On 24 July 2014 21:14, Petter Goksøyr Åsen <petter.goksoyr.asen@kul.oslo.kommune.no> wrote:
As for error returns: there is nothing wrong with returning a proper HTTP status code
AND  a human/machine-readable error message. In fact, that's what I would go for.
That way, the client can short circut just by checking the status code, or parse the response
if it needs to give some feedback ...

For example:
curl -i -X GET /rest/biblionr/1235
Returns:
HTTP/1.1 404 Not Found
Date: Thu, 24 Jul 2014 09:11:07 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

{ "error": "no record with biblilonumber 12345 found"}

Regards
Petter Goksøyr Åsen
Deichmanske bibliotek / Oslo Public Library


Yes, I think it comes down to a matter of preference. I can see good reasons to go either way on that. Going the other way is a little simpler to manage for me. And I'm certain some folks will feel more strongly about it than I do.





On 24 July 2014 18:59, David Cook <dcook@prosentient.com.au> wrote:

Hey Reed:

 

1)      I’ve wondered a bit about that as well. So far, everything I’ve looked at appears to handle PUT and DELETE just fine, but I’m definitely a bit wary of running into odd problems like that. I’d love to hear more about that from others.


I think it's not super likely that PUT and DELETE would be genuine problem on average. I probly worry too much.
 

2)      Agreed. I think POST for writes and GET for reads is the norm.

3)      Agreed. Returning HTML sounds like a horrible idea. I’d say XML or JSON.

4)      Could you clarify a bit more about what you mean a bout “API level exceptions”? When I first read that, I thought “he must be mad!” Then I started to think that perhaps you were talking about application level exceptions? Like…”borrowernumber” not found or something like that? I did something similar. When they didn’t provide the borrowernumber, I returned a successful response with an error message. I figure it’s more useful than a “bad request” http response or something of that sort. I suppose the only downside is that you need to know to check for the error in the response. So…it is tempting to use HTTP error responses instead.


Petter's example is probably a good illustration.

But, no, I take it to the extreme edge of reasonableness. Any application level error I can trap is wrapped in a message which I deliver to the client in an HTTP success response.

I should note at this point I'm doing this all in Python which makes that simpler.

My thinking is that I want to reserve HTTP errors for transport failures instead of application failures/errors.

And it does seem to simplify the way I think about the client/javascript layer of the application. All handled responses are dealt with in one place if they're successful HTTP requests and anything else is a generic catastrophe.

-reed

 

 

David Cook

Systems Librarian

Prosentient Systems

72/330 Wattle St, Ultimo, NSW 2007

 

From: koha-devel-bounces@lists.koha-community.org [mailto:koha-devel-bounces@lists.koha-community.org] On Behalf Of Reed Wade
Sent: Wednesday, 23 July 2014 8:09 PM
To: koha-devel@lists.koha-community.org


Subject: Re: [Koha-devel] RFC: /svc/ API

 

 

Just to add my bits regarding rest style APIs because I've been making a lot of those lately:

 

 

- sticking with GET and POST may simplify things because they're just a lot more typical and you're less likely to run into odd problems with less well tested lib and proxy support

- a great rule of thumb is POST for writes and GET for reads; this makes it intentionally harder to compose a url that accidentally writes anything

- avoid emitting HTML, the cool kids are letting the browser do all the work now

 

Some folks will not like the next bit of advice because it's not pure REST. I like to never return http error responses for API level exceptions. Instead I like to provide a "success" boolean value in the json response and a text explanation in a separate variable.

 

-reed