Re: [Koha-devel] RFC: /svc/ API
I'm so glad that you've asked these questions, Petter! 1) I would very much like to see Koha's HTTP APIs expanded. Locally, I've added some services for check-in and check-out, as we have a desktop app that does some circulation on behalf of Koha. More generally, I would like to see a richer HTTP API, so that we could more loosely couple Koha to other systems, especially in terms of OPAC functionality. We work with a lot of special libraries, so it would be great if they could use an API to integrate search and holds into their own websites. It would also be useful for discovery software (like VuFind) for getting real-time item availability information. I know BibLibre integrate Koha and Drupal (which might be the reason for their koha-restful code?). As for the staff client, I think it would still be useful, as it opens up more third-party involvement with Koha. If there were more services, we could do more with our desktop app. I'm sure that others would find uses for it as well. I think that this also has the potential to increase separation of business and presentation layers. Of course, I think presentation is important, but if we focus on making sure that useful data is coming out, we're less likely to cheat and combine them when we probably shouldn't. 2) I'm not sure that I understand what you mean when you ask "should Koha's templates make use of its own APIs?". Do you mean using the API via Javascript on the template, or using the API via LWP in the Perl script? In either case, I'm starting to think so. I think there is already a growing trend in Koha for using APIs via AJAX. As for using the APIs serverside, I don't know what implications that would have. 3) I agree with your library, Petter. I think that this would be a fruitful direction for Koha to go. I think that I could contribute some time and energy to this as well. I only heard of BibLibre's "koha-restful" recently. I didn't thoroughly review the code, but it appears that it only uses IP-based authentication at the moment. I think it was missing all the functionality that I desired as well, so I decided not to use it. I hope other people express an interest as well, as I really would like to see Koha become more service-oriented. David Cook Systems Librarian Prosentient Systems 72/330 Wattle St, Ultimo, NSW 2007 -----Original Message----- From: Petter Goksøyr Åsen [mailto:petter.goksoyr.asen@kul.oslo.kommune.no] Sent: Wednesday, 23 July 2014 12:11 PM To: David Cook Subject: SV: [Koha-devel] RFC: /svc/ API David Cook wrote:
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.
I agree. We should think twice before breaking existing integrations and workflows. I am also interested to hear peoples opinions about Koha's HTTP APIs in general: - do you want them expanded? for what use cases? - and more importantly: should Koha's templates make use of i'ts own APIs? My library certainly think this could be a fruitful direction for Koha to go, and want to help make it happen. But if there is no big interest in the community in this approach, we'll more likely to fork and/or contribute to Biblibre's koha-restful instead of patching the svc and ILS-DI APIs. Regards, Petter Goksøyr Åsen Deichmanske bibliotek / Oslo Public Library
2014-07-23 5:03 GMT+02:00 David Cook <dcook@prosentient.com.au>: Hi David,
I only heard of BibLibre's "koha-restful" recently. I didn't thoroughly review the code, but it appears that it only uses IP-based authentication at the moment. I think it was missing all the functionality that I desired as well, so I decided not to use it.
BibLibre wrote koha-restful to fix the lack of possibilities IDS-DI can provide. We are highly open-minded to contributions (merge request, patches, etc.), if you find some time :) If you want to add features, you can send us a patch at dev_patches AT biblibre DOT com You can find more information about it into README file and opac/rest.pl documentation on http://git.biblibre.com. Cheers, Jonathan
-----Original Message----- From: Petter Goksøyr Åsen [mailto:petter.goksoyr.asen@kul.oslo.kommune.no] Sent: Wednesday, 23 July 2014 12:11 PM To: David Cook Subject: SV: [Koha-devel] RFC: /svc/ API
David Cook wrote:
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.
I agree. We should think twice before breaking existing integrations and workflows.
I am also interested to hear peoples opinions about Koha's HTTP APIs in general: - do you want them expanded? for what use cases? - and more importantly: should Koha's templates make use of i'ts own APIs?
My library certainly think this could be a fruitful direction for Koha to go, and want to help make it happen. But if there is no big interest in the community in this approach, we'll more likely to fork and/or contribute to Biblibre's koha-restful instead of patching the svc and ILS-DI APIs.
Regards, Petter Goksøyr Åsen Deichmanske bibliotek / Oslo Public Library
_______________________________________________ Koha-devel mailing list Koha-devel@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/
Hi Jonathan: Thanks. I'll keep that in mind. We might need to use it for a certain project, so that's good to know. I'm a bit wary of using third-party software for Koha that we don’t maintain ourselves though :/. Is there any chance that BibLibre might be looking to merge the code into the community codebase? David Cook Systems Librarian Prosentient Systems 72/330 Wattle St, Ultimo, NSW 2007 -----Original Message----- From: druartjonathan@gmail.com [mailto:druartjonathan@gmail.com] On Behalf Of Jonathan Druart Sent: Wednesday, 23 July 2014 6:14 PM To: David Cook Cc: Petter Goksøyr Åsen; koha-devel@lists.koha-community.org Subject: Re: [Koha-devel] RFC: /svc/ API 2014-07-23 5:03 GMT+02:00 David Cook <dcook@prosentient.com.au>: Hi David,
I only heard of BibLibre's "koha-restful" recently. I didn't thoroughly review the code, but it appears that it only uses IP-based authentication at the moment. I think it was missing all the functionality that I desired as well, so I decided not to use it.
BibLibre wrote koha-restful to fix the lack of possibilities IDS-DI can provide. We are highly open-minded to contributions (merge request, patches, etc.), if you find some time :) If you want to add features, you can send us a patch at dev_patches AT biblibre DOT com You can find more information about it into README file and opac/rest.pl documentation on http://git.biblibre.com. Cheers, Jonathan
-----Original Message----- From: Petter Goksøyr Åsen [mailto:petter.goksoyr.asen@kul.oslo.kommune.no] Sent: Wednesday, 23 July 2014 12:11 PM To: David Cook Subject: SV: [Koha-devel] RFC: /svc/ API
David Cook wrote:
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.
I agree. We should think twice before breaking existing integrations and workflows.
I am also interested to hear peoples opinions about Koha's HTTP APIs in general: - do you want them expanded? for what use cases? - and more importantly: should Koha's templates make use of i'ts own APIs?
My library certainly think this could be a fruitful direction for Koha to go, and want to help make it happen. But if there is no big interest in the community in this approach, we'll more likely to fork and/or contribute to Biblibre's koha-restful instead of patching the svc and ILS-DI APIs.
Regards, Petter Goksøyr Åsen Deichmanske bibliotek / Oslo Public Library
_______________________________________________ Koha-devel mailing list Koha-devel@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/
Great comments, David! Thanks for taking the discussion further:) Some comments in line below: Fra: David Cook [dcook@prosentient.com.au]
I think that this also has the potential to increase separation of business and presentation layers. Of course, I think presentation is important, but if we focus on making sure that useful data is coming out, we're less likely to cheat and combine them when we probably shouldn't.
I agree - this would perhaps be the best takeaway, IMO.
2) I'm not sure that I understand what you mean when you ask "should Koha's templates make use of its own APIs?".
Do you mean using the API via Javascript on the template, or using the API via LWP in the Perl script?
Yes, I was thinking about such cases, as in recent enhancements using ajax+datatables for fetching data asynchronously. I also think it can be used for more static data, which rarely change. Say for example the list of branches (we have around 30) which populates dropdown several places the staff interface. If this was fetched after page load, by an AJAX request to, say, GET koha/rest/v2/branches, we could set the Cache expiration headers, (to a day, or a month, I dunno) then the browser would cache this particular request, and thus not touch the database at all except when cache expires. For frequently used pages this could lead to a lot of less traffic to the database. Then there is the problem of when you actually DO change this "mostly" static data, like branches... Well, either you can wait until cache expires, you can force to reload (Cltr +R, or Cltr + F5 in most browser), or we must implement some logic on updates which modifies the cache expiration headers. Some more benefits of Koha using its own APIs: - They are kept up to date since they are used by Kohas core - More thought is being put into layout, organization and implementation of the API, as it not just for "someone else", some third-party integration, but for Koha itself. Regards, Petter Goksøyr Åsen Deichmanske bibliotek / Oslo Public Library
You're very welcome, Petter. I'm happy to be having this discussion! I've included some inline comments below as well.
I also think it can be used for more static data, which rarely change. Say for example the list of branches (we have around 30) which populates dropdown several places the staff interface. If this was fetched after page load, by an AJAX request to, say, GET koha/rest/v2/branches, we could set the Cache expiration headers, (to a day, or a month, I dunno) then the browser would cache this particular request, and thus not touch the database at all except when cache expires. For frequently used pages this could lead to a lot of less traffic to the database. Then there is the problem of when you actually DO change this "mostly" static data, like branches... Well, either you can wait until cache expires, you can force to reload (Cltr +R, or Cltr + F5 in most browser), or we must implement some logic on updates which modifies the cache expiration headers.
I don't have much experience with caching, but that sounds interesting. One worry I have about using AJAX in the OPAC is the second or so that it can take to load an element on a page sometimes. The page loads and then elements can "jump". For instance, I added a drop-down menu for "Collection" next to the masthead search box. It didn't load very smoothly. I wonder if it would if it were cached as it doesn't need to do that database query. Of course, loading search result facets would take longer, but we could add a "Loading..." or "Calculating facets..." message in that case, so that users would know what the system is doing.
Some more benefits of Koha using its own APIs: - They are kept up to date since they are used by Kohas core - More thought is being put into layout, organization and implementation of the API, as it not just for "someone else", some third-party integration, but for Koha itself.
Agreed. Since Koha would be both client and server, I think more care would be put into architecture. Since it would depend on its own API, it would have to be up-to-date. David Cook Systems Librarian Prosentient Systems 72/330 Wattle St, Ultimo, NSW 2007
An interesting conversation all in all. I'm most certainly in favour of a well implemented restful api and dogfooding <http://en.wikipedia.org/wiki/Eating_your_own_dog_food> it for the opac so we keep it useful and up to date. I found this article very useful when crafting some api's for another product I work on regularly: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api As for the caching scenario, that's interesting indeed, and I can see huge advantages to gain here. I would suggest adding an optional hash/token to such requests and setting the cache time to 'forever'. That way we could link a change of the data to a change of the token, and hence manage the cache ourselves at the template level. If you want an idea of what I'm getting at, take a look at the docs for googles mod_pagespeed, as that's where I got my inspiration), or drop me a line for a chat. All exciting thoughts. I'll certainly be working on the API's at some point as part of our work using api's for the vufind connectors so I'm be happy to input a bit of time into this once the ball is rolling. Martin Martin Renvoize Software Engineer, PTFS Europe Ltd Content Management and Library Solutions Skype: Landline: 0203 286 8685 Mobile: 07725985636 http://www.ptfs-europe.com On 25 July 2014 01:15, David Cook <dcook@prosentient.com.au> wrote:
You're very welcome, Petter. I'm happy to be having this discussion!
I've included some inline comments below as well.
I also think it can be used for more static data, which rarely change. Say for example the list of branches (we have around 30) which populates dropdown several places the staff interface. If this was fetched after page load, by an AJAX request to, say, GET koha/rest/v2/branches, we could set the Cache expiration headers, (to a day, or a month, I dunno) then the browser would cache this particular request, and thus not touch the database at all except when cache expires. For frequently used pages this could lead to a lot of less traffic to the database. Then there is the problem of when you actually DO change this "mostly" static data, like branches... Well, either you can wait until cache expires, you can force to reload (Cltr +R, or Cltr + F5 in most browser), or we must implement some logic on updates which modifies the cache expiration headers.
I don't have much experience with caching, but that sounds interesting.
One worry I have about using AJAX in the OPAC is the second or so that it can take to load an element on a page sometimes. The page loads and then elements can "jump". For instance, I added a drop-down menu for "Collection" next to the masthead search box. It didn't load very smoothly. I wonder if it would if it were cached as it doesn't need to do that database query.
Of course, loading search result facets would take longer, but we could add a "Loading..." or "Calculating facets..." message in that case, so that users would know what the system is doing.
Some more benefits of Koha using its own APIs: - They are kept up to date since they are used by Kohas core - More thought is being put into layout, organization and implementation of the API, as it not just for "someone else", some third-party integration, but for Koha itself.
Agreed. Since Koha would be both client and server, I think more care would be put into architecture. Since it would depend on its own API, it would have to be up-to-date.
David Cook Systems Librarian Prosentient Systems 72/330 Wattle St, Ultimo, NSW 2007
_______________________________________________ Koha-devel mailing list Koha-devel@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/
participants (4)
-
David Cook -
Jonathan Druart -
Petter Goksøyr Åsen -
Renvoize, Martin