[Koha-devel] RFC: /svc/ API

[David Cook]

Ah, I hadn't thought of that. I like that, Petter!

David Cook
Systems Librarian
Prosentient Systems
72/330 Wattle St, Ultimo, NSW 2007

-----Original Message-----
From: koha-devel-bounces at lists.koha-community.org
[mailto:koha-devel-bounces at lists.koha-community.org] On Behalf Of Petter
Goksøyr Åsen
Sent: Thursday, 24 July 2014 7:14 PM
To: koha-devel at lists.koha-community.org
Subject: Re: [Koha-devel] RFC: /svc/ API

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
________________________________________
Fra: koha-devel-bounces at lists.koha-community.org
[koha-devel-bounces at lists.koha-community.org] på vegne av David Cook
[dcook at prosentient.com.au]
Sendt: 24. juli 2014 08:59
Til: 'Reed Wade'; koha-devel at lists.koha-community.org
Emne: Re: [Koha-devel] RFC: /svc/ API

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


_______________________________________________
Koha-devel mailing list
Koha-devel at lists.koha-community.org
http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
website : http://www.koha-community.org/ git :
http://git.koha-community.org/ bugs : http://bugs.koha-community.org/