[Koha-devel] RFC: /svc/ API

Thu Jul 24 04:26:39 CEST 2014

I’d be happy enough with a “/rest/v1” or something like that. Sure.

I haven’t seen “koha-restfull” in action, so I would probably want to test it quite a bit. As I pointed out before, I don’t think it does any authentication besides checking the “REMOTE_ADDR” environmental variable, which is problematic. First, that won’t work when Koha sits behind a reverse proxy (or rather…it could have horrible consequences if you allow the ip address for your reverse proxy as it means that “anyone” could access “koha-restfull”). Second, it bypasses Koha’s permission authorization system. Above all else, if we’re going to have a service layer, I think it needs to be reasonably secured. At the moment, anyone authenticated via an IP address could change the password for any user, delete users, etc. 

I think we’d want to spend some time considering what should be part of the “public” API and what should be part of the “private” API. The “public” search should respect “OpacSuppression”, while the “private” search would not. I suppose we could have one API, and control the output based on whether the user is authenticated into Koha and whether they’re authorized to use that particular part of the API. Mind you, if we have one API, I wonder where to put it…with the “intranet” code or the “opac” code (as in “koha-restfull”). Personally, it probably makes more sense to locate it with the “intranet” code as the majority of the API is probably going to need password protection. Exceptions being for “search” and real-time item “availability” probably (also accessing public lists, public tags, seeing ratings, public comments/reviews, and perhaps something else I haven’t thought of). Of course, users should be able to authenticate to Koha and be able to get the same data as they would if they logged into the OPAC. 

Maybe it’s worthwhile to have a public and a private API, although I wouldn’t want to duplicate code if we could avoid it. I suppose the “public” and “private” distinctions aren’t quite right. Rather, a “staff” API and a “user” API. 

Personally, I would love a user API that provides all the functionality of the current OPAC. I think that could lead to better integration with discovery services, potentially more mashups, integration with existing library and non-library websites. Theoretically, it could even “lighten the load” on Koha developers in terms of accessibility and UX. If we’re providing all the necessary data via an API, the OPAC becomes a default interface…while people can build their own interfaces if they desire. That puts the onus back on them, and it also creates some potential for innovation. People (especially “non-library” people) might find that they really would love to be able to do “X” on their site, but the API isn’t providing that data. We, the Koha developers, modify the API (or schedule it for the next version), and they, the users/librarians/other developers, get the data they need.

You could argue that a library management system really is the staff client. You need a public interface for people to search the library catalogue, to place holds, to have some of that Web 2.0 functionality, but… there’s no reason not to do it via an API and have the OPAC as the stock interface. I was thinking recently about “Koha”. 

What is Koha? Is Koha the staff client, the OPAC, or both? In my mind, I think of Koha as the staff client, and I think of the OPAC as the Koha OPAC. The OPAC isn’t really a management system per se. It’s an end-user interface. We give access to the library holdings and give users a way of interacting with those holdings online, but the actual “management” happens in the staff client. Ok, now I’m just rambling…

A “staff” API would be great as well for integrating with other tools such as MarcEdit, third-party apps, and for internal usage (as per Petter’s email). 

After reviewing the “koha-restfull” code a bit more, the use of CGI::Application::Dispatch does look pretty cool. 

I’m not 100% certain about the use of “POST” vs “PUT” in “koha-restfull” though. If I understand correctly, PUT should only be used when submitting a full resource (if you’re creating a resource or if you’re modifying it by submitting the entire resource), whereas POST should be used when making partial requests/modifications ( <http://restcookbook.com/HTTP%20Methods/idempotency/> http://restcookbook.com/HTTP%20Methods/idempotency/). If we’re to follow all the standards, I would suggest switching PUT and POST in our implementation of “/rest/v1/”. It might be a bit of a pedantic distinction, but it seems to be me that is how it is “supposed” to be done.

While I continue my pedantry, I’d want us to use English spellings like “restful” instead of “restfull”, and “information” instead of “informations”. Keeping in line with the “svc” context, I’d probably prefer “rest” (or “rest/v1”)to “rest.pl” as well. 

I suppose in terms of priority…I don’t know what to say. I have uses for both a “staff” and a “user” API. None of these uses are particularly urgent. If I need to use “koha-restfull” in the short-term, I’d contribute patches back to BibLibre’s repository.

Anyway, that’s my 2 cents (and then some) :p.

Hope to see more people interested in this. I suppose there isn’t a lot of incentive to focus on building a Restful API rather than continuing to work on the existing structure. I know I’m more concerned at the moment with improving framework management and search, but…I would really like to see a proper Restful API come about.

David Cook

Systems Librarian

Prosentient Systems

72/330 Wattle St, Ultimo, NSW 2007

From: Tomas Cohen Arazi [mailto:tomascohen at gmail.com] 
Sent: Thursday, 24 July 2014 10:30 AM
To: David Cook
Cc: Galen Charlton; koha-devel
Subject: Re: [Koha-devel] RFC: /svc/ API

We should do as we usually do: set a new context for URIs (/rest/ ?) and implement a RESTfull API there, following all the standards, and versioned from the beggining.

We could use CGI::Application::Dispatch, merge koha-restfull and work on top of that (it should be discussed whether we agree on the current API or not), or even do it with a framework, like Dancer [1].

And then have a clear deprecation path for the old API.

Would be happy to work on that if more people were interested.

[1] http://irc.koha-community.org/koha/2014-07-18#i_1538096

On Wed, Jul 23, 2014 at 9:21 PM, David Cook <dcook at prosentient.com.au <mailto:dcook at prosentient.com.au> > wrote:

Ah, right you are, Galen. It does use a socket. Yeah, that should be trivial to update connexion_import_daemon.pl <http://connexion_import_daemon.pl> .

None of our folks use OCLC, but that's good to know.

Going back to my earlier email, MarcEdit would probably benefit from a richer Koha API as well.

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

-----Original Message-----

From: Galen Charlton [mailto:gmc at esilibrary.com <mailto:gmc at esilibrary.com> ]
Sent: Thursday, 24 July 2014 1:22 AM
To: David Cook
Cc: koha-devel at lists.koha-community.org <mailto:koha-devel at lists.koha-community.org> 
Subject: Re: [Koha-devel] RFC: /svc/ API

Hi,

On Tue, Jul 22, 2014 at 5:11 PM, David Cook <dcook at prosentient.com.au <mailto:dcook at prosentient.com.au> > wrote:
> +1 to a versioned API. I don't think that I use it for anything at the
> moment, but I'm not 100% sure about all our apps. I think we might
> have a third-party one that uses it.

Also +1 to a versioned API.

> This script should probably also use PUT, but I have no idea if OCLC
> Connexion supports that.

I don't believe it matters as far as Connexion is concerned, as it only talks to connexion_import_daemon.pl <http://connexion_import_daemon.pl>  via a raw socket.

> Since there are an indeterminate number of third-party software
> systems using the existing API, I'd recommend versioning and using v2
> to handle things more RESTfully.

MarcEdit is one program I know that uses the current API to inject records into a Koha database.

Regards,

Galen
--
Galen Charlton
Manager of Implementation
Equinox Software, Inc. / The Open Source Experts
email:  gmc at esilibrary.com <mailto:gmc at esilibrary.com> 
direct: +1 770-709-5581
cell:   +1 404-984-4366
skype:  gmcharlt
web:    http://www.esilibrary.com/
Supporting Koha and Evergreen: http://koha-community.org & http://evergreen-ils.org

_______________________________________________
Koha-devel mailing list
Koha-devel at lists.koha-community.org <mailto: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/

-- 

Tomás Cohen Arazi

Prosecretaría de Informática

Universidad Nacional de Córdoba

✆ +54 351 5353750 ext 13168

GPG: B76C 6E7C 2D80 551A C765  E225 0A27 2EA1 B2F3 C15F

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20140724/1f834d08/attachment-0001.html>