[Koha-devel] RFC: /svc/ API

[David Cook]

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.

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.

 

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/70c6c3fd/attachment.html>