Re: [Koha-devel] RFC: /svc/ API
+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. As for PUT vs POST, I suppose strictly speaking PUT would be more appropriate for /svc/bib. In terms of difficulty, it would be fairly trivial to update our apps. It's worth remembering that the OCLC Connexion daemon "./misc/bin/connexion_import_daemon.pl" uses "/cgi-bin/koha/svc/import_bib". This script should probably also use PUT, but I have no idea if OCLC Connexion supports that. 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. David Cook Systems Librarian Prosentient Systems 72/330 Wattle St, Ultimo, NSW 2007 -----Original Message----- Date: Tue, 22 Jul 2014 00:42:35 +0000 From: Indranil Das Gupta <indradg@gmail.com> To: "koha-devel@lists.koha-community.org" <koha-devel@lists.koha-community.org> Subject: Re: [Koha-devel] RFC: /svc/ API Message-ID: <CAEm3SZ135wdeSV8uth63cQHi-B+UsdvxQiw+QesZD=Vo2kS+ew@mail.gmail.com> Content-Type: text/plain; charset=UTF-8 On Mon, Jul 21, 2014 at 7:46 PM, Chris Cormack <chrisc@catalyst.net.nz> wrote:
* Philippe Blouin (philippe.blouin@inlibro.com) wrote:
Hi, <snipped>
I think we you want to do something like this (change a published and in use API) then we should version it.
So that the current in use version can be version one, we make a new version 2 of the API people can transition to it. At some point in the future (maybe) we get rid of version 1
+1 Sounds reasonable. -- Indranil Das Gupta Phone : +91-98300-20971 Blog : http://indradg.randomink.org/blog IRC : indradg on irc://irc.freenode.net Twitter : indradg -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=- Please exchange editable Office documents only in ODF Format. No other format is acceptable. Support Open Standards. For a free editor supporting ODF, please visit LibreOffice - http://www.documentfoundation.org ------------------------------
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
Hello, Very interesting discussion! Petter Goksøyr Åsen writes:
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.
+1
I am also interested to hear peoples opinions about Koha's HTTP APIs in general: - do you want them expanded? for what use cases?
We would definitely be interested in having expanded APIs. We at PTFS Europe have been working on a revised VuFind driver which uses the ILS-DI API to provide functionality currently only available through direct database connections (https://github.com/PTFS-Europe/vufind/compare/vufind-org:master...koha-drive...). Parts of this driver unfortunately do not work yet due to limitations of the ILS-DI API, so we'd be keen to see it enhanced!
- and more importantly: should Koha's templates make use of i'ts own APIs?
I like this idea in principle, though am in no way capable of assessing the feasibility or practical implications in terms of relative performance and code complexity… Best wishes, Alex -- Sent with my mu4e
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
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@lists.koha-community.org [mailto:koha-devel-bounces@lists.koha-community.org] On Behalf Of Reed Wade Sent: Wednesday, 23 July 2014 8:09 PM To: koha-devel@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
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@lists.koha-community.org [koha-devel-bounces@lists.koha-community.org] på vegne av David Cook [dcook@prosentient.com.au] Sendt: 24. juli 2014 08:59 Til: 'Reed Wade'; koha-devel@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@lists.koha-community.org [mailto:koha-devel-bounces@lists.koha-community.org] On Behalf Of Reed Wade Sent: Wednesday, 23 July 2014 8:09 PM To: koha-devel@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
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@lists.koha-community.org [mailto:koha-devel-bounces@lists.koha-community.org] On Behalf Of Petter Goksøyr Åsen Sent: Thursday, 24 July 2014 7:14 PM To: koha-devel@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@lists.koha-community.org [koha-devel-bounces@lists.koha-community.org] på vegne av David Cook [dcook@prosentient.com.au] Sendt: 24. juli 2014 08:59 Til: 'Reed Wade'; koha-devel@lists.koha-community.org Emne: Re: [Koha-devel] RFC: /svc/ API Hey Reed: 1) Ive wondered a bit about that as well. So far, everything Ive looked at appears to handle PUT and DELETE just fine, but Im definitely a bit wary of running into odd problems like that. Id 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. Id 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 didnt provide the borrowernumber, I returned a successful response with an error message. I figure its 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@lists.koha-community.org [mailto:koha-devel-bounces@lists.koha-community.org] On Behalf Of Reed Wade Sent: Wednesday, 23 July 2014 8:09 PM To: koha-devel@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@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/
On 24 July 2014 21:14, Petter Goksøyr Åsen < petter.goksoyr.asen@kul.oslo.kommune.no> wrote:
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
Yes, I think it comes down to a matter of preference. I can see good reasons to go either way on that. Going the other way is a little simpler to manage for me. And I'm certain some folks will feel more strongly about it than I do. On 24 July 2014 18:59, David Cook <dcook@prosentient.com.au> wrote:
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.
I think it's not super likely that PUT and DELETE would be genuine problem on average. I probly worry too much. 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.
Petter's example is probably a good illustration. But, no, I take it to the extreme edge of reasonableness. Any application level error I can trap is wrapped in a message which I deliver to the client in an HTTP success response. I should note at this point I'm doing this all in Python which makes that simpler. My thinking is that I want to reserve HTTP errors for transport failures instead of application failures/errors. And it does seem to simplify the way I think about the client/javascript layer of the application. All handled responses are dealt with in one place if they're successful HTTP requests and anything else is a generic catastrophe. -reed
David Cook
Systems Librarian
Prosentient Systems
72/330 Wattle St, Ultimo, NSW 2007
*From:* koha-devel-bounces@lists.koha-community.org [mailto: koha-devel-bounces@lists.koha-community.org] *On Behalf Of *Reed Wade *Sent:* Wednesday, 23 July 2014 8:09 PM *To:* koha-devel@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
Hi, On Tue, Jul 22, 2014 at 5:11 PM, David Cook <dcook@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 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@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
Ah, right you are, Galen. It does use a socket. Yeah, that should be trivial to update 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@esilibrary.com] Sent: Thursday, 24 July 2014 1:22 AM To: David Cook Cc: koha-devel@lists.koha-community.org Subject: Re: [Koha-devel] RFC: /svc/ API Hi, On Tue, Jul 22, 2014 at 5:11 PM, David Cook <dcook@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 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@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
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@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.
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@esilibrary.com] Sent: Thursday, 24 July 2014 1:22 AM To: David Cook Cc: koha-devel@lists.koha-community.org Subject: Re: [Koha-devel] RFC: /svc/ API
Hi,
On Tue, Jul 22, 2014 at 5:11 PM, David Cook <dcook@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 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@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@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
We at BibLibre wrote koha-restful as a third-party application to be able to extend it quickly. Now that things are more stable (the last commit was written a month ago), I would be happy to submit a patch to integrate koha-restful into Koha. But IMO it lacks a decent identification/authentication system before it could be integrated. So if someone is interested to work on that, he is welcome :) Le 24/07/2014 02:30, Tomas Cohen Arazi a écrit :
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@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.
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@esilibrary.com] Sent: Thursday, 24 July 2014 1:22 AM To: David Cook Cc: koha-devel@lists.koha-community.org Subject: Re: [Koha-devel] RFC: /svc/ API
Hi,
On Tue, Jul 22, 2014 at 5:11 PM, David Cook <dcook@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 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@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@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/
_______________________________________________ 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/
-- Julian Maurice <julian.maurice@biblibre.com> BibLibre
Awesome. Thanks, Julian! As for authentication, I think adding a call to C4::Auth:: check_api_auth() in rest.pl should probably do the trick. David Cook Systems Librarian Prosentient Systems 72/330 Wattle St, Ultimo, NSW 2007
-----Original Message----- From: koha-devel-bounces@lists.koha-community.org [mailto:koha-devel- bounces@lists.koha-community.org] On Behalf Of Julian Maurice Sent: Wednesday, 30 July 2014 6:42 PM To: koha-devel@lists.koha-community.org Subject: Re: [Koha-devel] RFC: /svc/ API
We at BibLibre wrote koha-restful as a third-party application to be able to extend it quickly. Now that things are more stable (the last commit was written a month ago), I would be happy to submit a patch to integrate koha-restful into Koha. But IMO it lacks a decent identification/authentication system before it could be integrated. So if someone is interested to work on that, he is welcome :)
Le 24/07/2014 02:30, Tomas Cohen Arazi a écrit :
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@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.
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@esilibrary.com] Sent: Thursday, 24 July 2014 1:22 AM To: David Cook Cc: koha-devel@lists.koha-community.org Subject: Re: [Koha-devel] RFC: /svc/ API
Hi,
On Tue, Jul 22, 2014 at 5:11 PM, David Cook <dcook@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 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@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@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/
_______________________________________________ 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/
-- Julian Maurice <julian.maurice@biblibre.com> BibLibre _______________________________________________ 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/
I was thinking about how to transmit user credentials from the third-party application to Koha. Something using private/public keys like Amazon AWS seems the way to go. Example: http://www.thebuzzmedia.com/designing-a-secure-rest-api-without-oauth-authen... Le 31/07/2014 02:09, David Cook a écrit :
Awesome. Thanks, Julian!
As for authentication, I think adding a call to C4::Auth:: check_api_auth() in rest.pl should probably do the trick.
David Cook Systems Librarian Prosentient Systems 72/330 Wattle St, Ultimo, NSW 2007
-----Original Message----- From: koha-devel-bounces@lists.koha-community.org [mailto:koha-devel- bounces@lists.koha-community.org] On Behalf Of Julian Maurice Sent: Wednesday, 30 July 2014 6:42 PM To: koha-devel@lists.koha-community.org Subject: Re: [Koha-devel] RFC: /svc/ API
We at BibLibre wrote koha-restful as a third-party application to be able to extend it quickly. Now that things are more stable (the last commit was written a month ago), I would be happy to submit a patch to integrate koha-restful into Koha. But IMO it lacks a decent identification/authentication system before it could be integrated. So if someone is interested to work on that, he is welcome :)
Le 24/07/2014 02:30, Tomas Cohen Arazi a écrit :
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@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.
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@esilibrary.com] Sent: Thursday, 24 July 2014 1:22 AM To: David Cook Cc: koha-devel@lists.koha-community.org Subject: Re: [Koha-devel] RFC: /svc/ API
Hi,
On Tue, Jul 22, 2014 at 5:11 PM, David Cook <dcook@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 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@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@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/
_______________________________________________ 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/
-- Julian Maurice <julian.maurice@biblibre.com> BibLibre _______________________________________________ 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/
-- Julian Maurice <julian.maurice@biblibre.com> BibLibre
participants (7)
-
Alex Sassmannshausen -
David Cook -
Galen Charlton -
Julian Maurice -
Petter Goksøyr Åsen -
Reed Wade -
Tomas Cohen Arazi