[Koha-devel] RFC: /svc/ API

[Reed Wade]

On 24 July 2014 21:14, Petter Goksøyr Åsen <
petter.goksoyr.asen at 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 at 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 at lists.koha-community.org [mailto:
> koha-devel-bounces at lists.koha-community.org] *On Behalf Of *Reed Wade
> *Sent:* Wednesday, 23 July 2014 8:09 PM
> *To:* koha-devel at 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
>
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20140724/0bb59d5c/attachment.html>