<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"><head><meta http-equiv=Content-Type content="text/html; charset=utf-8"><meta name=Generator content="Microsoft Word 15 (filtered medium)"><style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:"Segoe UI Symbol";
panose-1:2 11 5 2 4 2 4 2 2 3;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
mso-fareast-language:EN-US;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]--></head><body lang=EN-AU link=blue vlink=purple><div class=WordSection1><p class=MsoNormal><a name="_MailEndCompose"><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>I’d be happy enough with a “/rest/v1” or something like that. Sure.<o:p></o:p></span></a></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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. <o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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. <o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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. <o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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.<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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”. <o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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…<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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). <o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>After reviewing the “koha-restfull” code a bit more, the use of CGI::Application::Dispatch does look pretty cool. <o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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 (</span><a href="http://restcookbook.com/HTTP%20Methods/idempotency/"><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";mso-fareast-language:EN-US'>http://restcookbook.com/HTTP%20Methods/idempotency/</span></a><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>). 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.<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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. <o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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.<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>Anyway, that’s my 2 cents (and then some) :p.<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>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.<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D'>David Cook<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D'>Systems Librarian<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D'>Prosentient Systems<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D'>72/330 Wattle St, Ultimo, NSW 2007<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>From:</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> Tomas Cohen Arazi [mailto:tomascohen@gmail.com] <br><b>Sent:</b> Thursday, 24 July 2014 10:30 AM<br><b>To:</b> David Cook<br><b>Cc:</b> Galen Charlton; koha-devel<br><b>Subject:</b> Re: [Koha-devel] RFC: /svc/ API<o:p></o:p></span></p><p class=MsoNormal><o:p> </o:p></p><div><p class=MsoNormal>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.<o:p></o:p></p><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>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].<o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>And then have a clear deprecation path for the old API.<o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>Would be happy to work on that if more people were interested.<o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>[1] <a href="http://irc.koha-community.org/koha/2014-07-18#i_1538096">http://irc.koha-community.org/koha/2014-07-18#i_1538096</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div></div><div><p class=MsoNormal style='margin-bottom:12.0pt'><o:p> </o:p></p><div><p class=MsoNormal>On Wed, Jul 23, 2014 at 9:21 PM, David Cook <<a href="mailto:dcook@prosentient.com.au" target="_blank">dcook@prosentient.com.au</a>> wrote:<o:p></o:p></p><blockquote style='border:none;border-left:solid #CCCCCC 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-right:0cm'><p class=MsoNormal>Ah, right you are, Galen. It does use a socket. Yeah, that should be trivial to update <a href="http://connexion_import_daemon.pl" target="_blank">connexion_import_daemon.pl</a>.<br><br>None of our folks use OCLC, but that's good to know.<br><br>Going back to my earlier email, MarcEdit would probably benefit from a richer Koha API as well.<o:p></o:p></p><div><p class=MsoNormal><br>David Cook<br>Systems Librarian<br>Prosentient Systems<br>72/330 Wattle St, Ultimo, NSW 2007<br><br>-----Original Message-----<o:p></o:p></p></div><div><p class=MsoNormal style='margin-bottom:12.0pt'>From: Galen Charlton [mailto:<a href="mailto:gmc@esilibrary.com">gmc@esilibrary.com</a>]<br>Sent: Thursday, 24 July 2014 1:22 AM<br>To: David Cook<br>Cc: <a href="mailto:koha-devel@lists.koha-community.org">koha-devel@lists.koha-community.org</a><br>Subject: Re: [Koha-devel] RFC: /svc/ API<o:p></o:p></p></div><div><div><p class=MsoNormal>Hi,<br><br>On Tue, Jul 22, 2014 at 5:11 PM, David Cook <<a href="mailto:dcook@prosentient.com.au">dcook@prosentient.com.au</a>> wrote:<br>> +1 to a versioned API. I don't think that I use it for anything at the<br>> moment, but I'm not 100% sure about all our apps. I think we might<br>> have a third-party one that uses it.<br><br>Also +1 to a versioned API.<br><br>> This script should probably also use PUT, but I have no idea if OCLC<br>> Connexion supports that.<br><br>I don't believe it matters as far as Connexion is concerned, as it only talks to <a href="http://connexion_import_daemon.pl" target="_blank">connexion_import_daemon.pl</a> via a raw socket.<br><br>> Since there are an indeterminate number of third-party software<br>> systems using the existing API, I'd recommend versioning and using v2<br>> to handle things more RESTfully.<br><br>MarcEdit is one program I know that uses the current API to inject records into a Koha database.<br><br>Regards,<br><br>Galen<br>--<br>Galen Charlton<br>Manager of Implementation<br>Equinox Software, Inc. / The Open Source Experts<br>email: <a href="mailto:gmc@esilibrary.com">gmc@esilibrary.com</a><br>direct: +1 770-709-5581<br>cell: +1 404-984-4366<br>skype: gmcharlt<br>web: <a href="http://www.esilibrary.com/" target="_blank">http://www.esilibrary.com/</a><br>Supporting Koha and Evergreen: <a href="http://koha-community.org" target="_blank">http://koha-community.org</a> & <a href="http://evergreen-ils.org" target="_blank">http://evergreen-ils.org</a><br><br><br>_______________________________________________<br>Koha-devel mailing list<br><a href="mailto:Koha-devel@lists.koha-community.org">Koha-devel@lists.koha-community.org</a><br><a href="http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel" target="_blank">http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel</a><br>website : <a href="http://www.koha-community.org/" target="_blank">http://www.koha-community.org/</a><br>git : <a href="http://git.koha-community.org/" target="_blank">http://git.koha-community.org/</a><br>bugs : <a href="http://bugs.koha-community.org/" target="_blank">http://bugs.koha-community.org/</a><o:p></o:p></p></div></div></blockquote></div><p class=MsoNormal><br><br clear=all><o:p></o:p></p><div><p class=MsoNormal><o:p> </o:p></p></div><p class=MsoNormal>-- <o:p></o:p></p><div><div><p class=MsoNormal>Tomás Cohen Arazi<o:p></o:p></p></div><div><p class=MsoNormal>Prosecretaría de Informática<o:p></o:p></p></div><div><p class=MsoNormal>Universidad Nacional de Córdoba<o:p></o:p></p></div><div><p class=MsoNormal><span style='font-family:"Segoe UI Symbol","sans-serif"'>✆</span> +54 351 5353750 ext 13168<o:p></o:p></p></div><div><p class=MsoNormal>GPG: B76C 6E7C 2D80 551A C765 E225 0A27 2EA1 B2F3 C15F<o:p></o:p></p></div></div></div></div></body></html>