Re: [Koha-devel] Marseille16 / REST api

[Tomas Cohen Arazi]

I didn't find you on IRC to talk about it, so I'll do it here.

El jue., 13 oct. 2016 a las 1:52, David Cook ()
escribió:

> However, that’s more human readable than machine readable. Let’s say we’re
> doing a CRUD form for the web UI, and we have something like
> Koha::Exceptions::Object::ValueInvalid. I think we’d want an error code
> or error message that would be easy to catch in the code, and then we relay
> that to the template in a way which allows for translation.
>

You should look at Jonathan's work on Koha::Virtualshel(f|ves) classes, and
how exceptions are handled in (say) shelves.pl because it will be
enlightning on what we were thinking of. It of course covers all your
questions, because that's what we were thinking of.

By the time he wrote that, there was no opinion on Try::Tiny, so he uses
eval, but he propagates the exception information up to the template file
as you suggest you would need to do on your work.

-- 
Tomás Cohen Arazi
Theke Solutions (https://theke.io )
✆ +54 9351 3513384
GPG: B2F3C15F
___
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/

Re: [Koha-devel] Marseille16 / REST api

[Tomas Cohen Arazi]

The code you highlighted comes from the unit tests. That's why it seems too
generic.
If you look at the actual controller class code, you will notice we are
catching several kinds of exceptions and doing what needs to be done on
each. But we still have the possibility that another exception we didn't
consider reached the controller, hence the 'Something went wrong, see the
logs' generic message. It's a catch-all fallback.

Regarding the error codes, we have followed what seemed the regular use in
bibliography, which is of course subject to discussion/improvement. But
keep in mind that it is mostly bad formed data, or non existing fields
attempted to be updated/created, so I think the 500 is a good idea. What
error you think would suit better?

BTW, Martin highlighted yesterday that we could make heavier use of swagger
for parameters validation, so in theory we should not hit the controller
script (not to speak of dbix) if parameters are wrong. I have the feeling
we shouldn't, because the trade off in terms of bureaucracy on writing json
files is quite negative.

Anyway, I still think it makes a whole lot of sense that we raise an
exception on Koha::Objects if dbix would die due to bad parameters, don't
you think?

El jue., 13 de oct. de 2016 2:08 AM, David Cook <dc...@prosentient.com.au>
escribió:

> Cheers, Fridolin!
>
> In terms of CRUD endpoints, I wonder how it would work for end users...
> looking at https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=17428,
> the messages seem a bit strange to me.
>
> { error => "Something went wrong, check the logs." }, 500 );
>
> That might make sense if it's just Koha consuming Koha services, but what
> about third-parties?
>
> I imagine it more like the Spotify API:
> https://developer.spotify.com/web-api/get-album/
> https://developer.spotify.com/web-api/user-guide/#response-status-codes
> https://developer.spotify.com/web-api/user-guide/#error-details
>
> You return the HTTP code and then you have a standard format for details.
> With a 500 error, I don't think you'd actually send a message, since you
> don't really have anything to say, since it's an internal server error.
>
> Actually, I'm not sure about  the use of 500 for DBIx::Class::Exception...
> but I haven't looked into our use of that exception yet. If you've provided
> a bad value or a bad field, maybe it would make more sense to return 400
> for a bad request rather than saying there was an internal server error
> which tend to arise unexpectedly. Bad values or bad fields are somewhat
> predictable.
>
> Anyway, I'm just curious about whatever conventions we use, so that I can
> apply them consistently in whatever code I (and others) contribute.
>
> David Cook
> Systems Librarian
> Prosentient Systems
> 72/330 Wattle St
> Ultimo, NSW 2007
> Australia
>
> Office: 02 9212 0899
> Direct: 02 8005 0595
>
> > -Original Message-
> > From: koha-devel-boun...@lists.koha-community.org [mailto:koha-devel-
> > boun...@lists.koha-community.org] On Behalf Of Fridolin SOMERS
> > Sent: Wednesday, 12 October 2016 6:32 PM
> > To: koha-devel@lists.koha-community.org
> > Subject: Re: [Koha-devel] Marseille16 / REST api
> >
> > Here are my notes :
> > https://wiki.koha-
> > community.org/wiki/Marseille_hackfest_2016#REST_API_-_Thomas
> >
> >
> > Le 12/10/2016 à 09:17, Tomas Cohen Arazi a écrit :
> > > El mié., 12 oct. 2016 a las 7:26, David Cook
> > > (<dc...@prosentient.com.au>)
> > > escribió:
> > >
> > >> Really curious to see how this plays out!
> > >>
> > >>
> > >>
> > >> I’ve just added parameter validation to a Koha::Object, and while it
> > >> works well enough, I’m hoping for a more generalized solution. I
> > >> haven’t looked at Koha::Exceptions::* yet, but maybe that will help.
> > >>
> > >
> > > I don't know how that would work, what bug number is it?
> > >
> > >
> > >> Peeking at Koha::Exceptions::MissingParameter, I hope that there’s
> > >> more specificity than just “A required parameter is missing”. I’d
> > >> want to know which required parameter is missing.
> > >>
> > >>
> > >>
> > >> Is there a document somewhere saying how to use Koha::Exceptions?
> > >>
> > >
> > > Well, we are not baking our own exception system, we are just using
> > > Class::Exception so it is pretty documented!
> > >
> > > Look at bug 17425, you will notice when we throw an exception we can
> > > add a message.
> > >
> > > Regards!
> > >
> > >

Re: [Koha-devel] Marseille16 / REST api

[David Cook]

Cheers, Fridolin!

In terms of CRUD endpoints, I wonder how it would work for end users... looking 
at https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=17428, the 
messages seem a bit strange to me.

{ error => "Something went wrong, check the logs." }, 500 );

That might make sense if it's just Koha consuming Koha services, but what about 
third-parties? 

I imagine it more like the Spotify API:
https://developer.spotify.com/web-api/get-album/
https://developer.spotify.com/web-api/user-guide/#response-status-codes
https://developer.spotify.com/web-api/user-guide/#error-details

You return the HTTP code and then you have a standard format for details. With 
a 500 error, I don't think you'd actually send a message, since you don't 
really have anything to say, since it's an internal server error.

Actually, I'm not sure about  the use of 500 for DBIx::Class::Exception... but 
I haven't looked into our use of that exception yet. If you've provided a bad 
value or a bad field, maybe it would make more sense to return 400 for a bad 
request rather than saying there was an internal server error which tend to 
arise unexpectedly. Bad values or bad fields are somewhat predictable. 

Anyway, I'm just curious about whatever conventions we use, so that I can apply 
them consistently in whatever code I (and others) contribute. 

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

Office: 02 9212 0899
Direct: 02 8005 0595

> -Original Message-
> From: koha-devel-boun...@lists.koha-community.org [mailto:koha-devel-
> boun...@lists.koha-community.org] On Behalf Of Fridolin SOMERS
> Sent: Wednesday, 12 October 2016 6:32 PM
> To: koha-devel@lists.koha-community.org
> Subject: Re: [Koha-devel] Marseille16 / REST api
> 
> Here are my notes :
> https://wiki.koha-
> community.org/wiki/Marseille_hackfest_2016#REST_API_-_Thomas
> 
> 
> Le 12/10/2016 à 09:17, Tomas Cohen Arazi a écrit :
> > El mié., 12 oct. 2016 a las 7:26, David Cook
> > (<dc...@prosentient.com.au>)
> > escribió:
> >
> >> Really curious to see how this plays out!
> >>
> >>
> >>
> >> I’ve just added parameter validation to a Koha::Object, and while it
> >> works well enough, I’m hoping for a more generalized solution. I
> >> haven’t looked at Koha::Exceptions::* yet, but maybe that will help.
> >>
> >
> > I don't know how that would work, what bug number is it?
> >
> >
> >> Peeking at Koha::Exceptions::MissingParameter, I hope that there’s
> >> more specificity than just “A required parameter is missing”. I’d
> >> want to know which required parameter is missing.
> >>
> >>
> >>
> >> Is there a document somewhere saying how to use Koha::Exceptions?
> >>
> >
> > Well, we are not baking our own exception system, we are just using
> > Class::Exception so it is pretty documented!
> >
> > Look at bug 17425, you will notice when we throw an exception we can
> > add a message.
> >
> > Regards!
> >
> >
> >>
> >> David Cook
> >>
> >> Systems Librarian
> >>
> >> Prosentient Systems
> >>
> >> 72/330 Wattle St
> >>
> >> Ultimo, NSW 2007
> >>
> >> Australia
> >>
> >>
> >>
> >> Office: 02 9212 0899 <02%2092%2012%2008%2099>
> >>
> >> Direct: 02 8005 0595 <02%2080%2005%2005%2095>
> >>
> >>
> >>
> >> *From:* koha-devel-boun...@lists.koha-community.org [mailto:
> >> koha-devel-boun...@lists.koha-community.org] *On Behalf Of *Tomas
> >> Cohen Arazi
> >> *Sent:* Wednesday, 12 October 2016 2:39 AM
> >> *To:* koha-devel <koha-devel@lists.koha-community.org>
> >> *Subject:* [Koha-devel] Marseille16 / REST api
> >>
> >>
> >>
> >> During the first couple Hackfest days, Jonathan, Benjamin and I
> >> worked on a reference implementation of CRUD code for a REST
> >> endpoint, so others can read it, discuss it and use it as a reference for
> their own developments.
> >>
> >>
> >>
> >> We worked on Koha::Cit(y|ies) because it was a really simple class.
> >> All our work is now on bug 17428.
> >>
> >>
> >>
> >> The main goals/concepts we tried to apply were:
> >>
> >> * Controller class (Koha::REST::V1::Cities) should be as simple as
> >> possible. No business logic on it. All business logic is expected to
> >> be put on the Koha::Cit(ies|y) classes. And fully tested.
> >>
> >>

Re: [Koha-devel] Marseille16 / REST api

[David Cook]

Hi Tomas,

 

It’s bug 10662, but I haven’t posted the revised patches with the parameter 
validation yet.

 

After reviewing bug 17425 and the documentation for Class::Exception, I see 
what you’re saying.

 

These two sections are the part that explain it for me best:

 
<http://search.cpan.org/~drolsky/Exception-Class-1.40/lib/Exception/Class/Base.pm#MyException->throw(_$message_)>
 
http://search.cpan.org/~drolsky/Exception-Class-1.40/lib/Exception/Class/Base.pm#MyException->throw(_$message_)

 
<http://search.cpan.org/~drolsky/Exception-Class-1.40/lib/Exception/Class/Base.pm#$exception->message()>
 
http://search.cpan.org/~drolsky/Exception-Class-1.40/lib/Exception/Class/Base.pm#$exception->message()

 

However, I think there’s still room for convention.

 

For instance:

 

try {

$patron->blah('blah');

} catch {

ok( $_->isa('Koha::Exceptions::Object::MethodNotFound'),

'Calling a non-existent method should raise a 
Koha::Exceptions::Object::MethodNotFound exception' );

};

 

This is a basic example… I’d want to see “which” method was not found. Of 
course, Object.pm defines that in the exception:

 

Koha::Exceptions::Object::MethodNotFound->throw( "No method $method for " . 
ref($self) );

Koha::Exceptions::Object::PropertyNotFound->throw( "No property $p for " . 
ref($self) );

 

However, that’s more human readable than machine readable. Let’s say we’re 
doing a CRUD form for the web UI, and we have something like 
Koha::Exceptions::Object::ValueInvalid. I think we’d want an error code or 
error message that would be easy to catch in the code, and then we relay that 
to the template in a way which allows for translation. 

 

In my code, I’ve been doing it like in my .pm/.pl:

 

$errors->{url}->{invalid_scheme} = 1;

 

Then in the template:

 

[% IF ( errors.url.invalid_scheme ) %]

Your url must start with http:// or https://

[% END %]

 

While my approach works, I don’t know that I’ve seen it elsewhere in Koha, and 
it just feels a bit… suboptimal to me. I don’t know why.

 

I suppose if I were using exceptions… it might be something like 
Koha::Exceptions::URI::InvalidScheme, and I’d probably be manually throwing 
that error in my processing of the CRUD form (since different forms might 
accept URIs with different schemes). I suppose in this case I don’t necessarily 
need the URI scheme that they did use… I just need to tell them the one that 
they “need to use” and I know that based on my controller’s logic and display 
it with the view. I suppose if they did use a scheme like “ftp”, I would know 
about it since I’m trying to catch that exception… and then pass it to the view 
if necessary.

 

So I guess in the end my questions are a bit irrelevant in terms of exceptions 
per se and relate to how we surface errors for users in a consistent way…

 

David Cook

Systems Librarian

Prosentient Systems

72/330 Wattle St

Ultimo, NSW 2007

Australia

 

Office: 02 9212 0899

Direct: 02 8005 0595

 

From: Tomas Cohen Arazi [mailto:tomasco...@gmail.com] 
Sent: Wednesday, 12 October 2016 6:17 PM
To: David Cook <dc...@prosentient.com.au>; koha-devel 
<koha-devel@lists.koha-community.org>
Subject: Re: [Koha-devel] Marseille16 / REST api

 

 

El mié., 12 oct. 2016 a las 7:26, David Cook (<dc...@prosentient.com.au 
<mailto:dc...@prosentient.com.au> >) escribió:

Really curious to see how this plays out!

 

I’ve just added parameter validation to a Koha::Object, and while it works well 
enough, I’m hoping for a more generalized solution. I haven’t looked at 
Koha::Exceptions::* yet, but maybe that will help.

 

I don't know how that would work, what bug number is it?

 

Peeking at Koha::Exceptions::MissingParameter, I hope that there’s more 
specificity than just “A required parameter is missing”. I’d want to know which 
required parameter is missing.

 

Is there a document somewhere saying how to use Koha::Exceptions?

 

Well, we are not baking our own exception system, we are just using 
Class::Exception so it is pretty documented!

 

Look at bug 17425, you will notice when we throw an exception we can add a 
message.

 

Regards!

 

 

David Cook

Systems Librarian

Prosentient Systems

72/330 Wattle St

Ultimo, NSW 2007

Australia

 

Office: 02 9212 0899 <tel:02%2092%2012%2008%2099> 

Direct: 02 8005 0595 <tel:02%2080%2005%2005%2095> 

 

From: koha-devel-boun...@lists.koha-community.org 
<mailto:koha-devel-boun...@lists.koha-community.org>  
[mailto:koha-devel-boun...@lists.koha-community.org 
<mailto:koha-devel-boun...@lists.koha-community.org> ] On Behalf Of Tomas Cohen 
Arazi
Sent: Wednesday, 12 October 2016 2:39 AM
To: koha-devel <koha-devel@lists.koha-community.org 
<mailto:koha-devel@lists.koha-community.org> >
Subject: [Koha-devel] Marseille16 / REST api

 

During the first couple

Re: [Koha-devel] Marseille16 / REST api

[Fridolin SOMERS]

Here are my notes :
https://wiki.koha-community.org/wiki/Marseille_hackfest_2016#REST_API_-_Thomas


Le 12/10/2016 à 09:17, Tomas Cohen Arazi a écrit :

El mié., 12 oct. 2016 a las 7:26, David Cook ()
escribió:


Really curious to see how this plays out!



I’ve just added parameter validation to a Koha::Object, and while it works
well enough, I’m hoping for a more generalized solution. I haven’t looked
at Koha::Exceptions::* yet, but maybe that will help.



I don't know how that would work, what bug number is it?



Peeking at Koha::Exceptions::MissingParameter, I hope that there’s more
specificity than just “A required parameter is missing”. I’d want to know
which required parameter is missing.



Is there a document somewhere saying how to use Koha::Exceptions?



Well, we are not baking our own exception system, we are just using
Class::Exception so it is pretty documented!

Look at bug 17425, you will notice when we throw an exception we can add a
message.

Regards!




David Cook

Systems Librarian

Prosentient Systems

72/330 Wattle St

Ultimo, NSW 2007

Australia



Office: 02 9212 0899 <02%2092%2012%2008%2099>

Direct: 02 8005 0595 <02%2080%2005%2005%2095>



*From:* koha-devel-boun...@lists.koha-community.org [mailto:
koha-devel-boun...@lists.koha-community.org] *On Behalf Of *Tomas Cohen
Arazi
*Sent:* Wednesday, 12 October 2016 2:39 AM
*To:* koha-devel 
*Subject:* [Koha-devel] Marseille16 / REST api



During the first couple Hackfest days, Jonathan, Benjamin and I worked on
a reference implementation of CRUD code for a REST endpoint, so others can
read it, discuss it and use it as a reference for their own developments.



We worked on Koha::Cit(y|ies) because it was a really simple class. All
our work is now on bug 17428.



The main goals/concepts we tried to apply were:

* Controller class (Koha::REST::V1::Cities) should be as simple as
possible. No business logic on it. All business logic is expected to be put
on the Koha::Cit(ies|y) classes. And fully tested.

* All verbs/use cases should be covered by tests
(t/db_dependent/api/v1/cities.t). We did it, and this file could be used
(with little adjustments) as the basis for new endpoint tests.

* Heavy use of exceptions. I wouldn't say we heavily use them, but the
point is that we pass everything to the business object, and catch
exceptions it might raise. Martin pointed out that he would help us further
simplify it, making heavier use of the Swagger plugin's facilities.
Specially on parameters sanity check. More on this tomorrow!

* Koha::Exceptions got per-class files so the exceptions file is more
manageable. Bug 17425 introduced Koha/Exceptions/Object.pm, and we propose
that's the way to go (Koha/Exceptions.pm still has Virtualshelves-related
exceptions that should be moved).

* Make use of Try::Tiny for try/catch blocks. On the process we wrote
bug 17425, which introduces new exceptions, we added the dependency for
Try::Tiny (no worries, it is packaged for Jessie/Ubuntu) and Mirko was here
to validate.

* Moving business-logic to Koha:: namespace and write REST endpoints on
top of that business objects. We picked a simple object, Koha::Patron(s)
will be a more complex one of course. This is what Jonathan has been doing,
and people willing to write REST endpoints should check with him, and
probably help moving business logic into Koha:: namespace.



There are several patches on bugzilla introducing endpoints. We will try
to contact patch authors to help them make their work match this proposed
'guidelines'.



We are sticking to the 'patches speak' approach, so feel free to criticize
this implementation, to improve it or even provide a counter-proposal. We
are otherwise moving on, trying to get a functional complete REST api ASAP.



Thanks!



Tomas, Jonathan, Benjamin







--

Tomás Cohen Arazi

Theke Solutions (https://theke.io )
✆ +54 9351 3513384 <+54%209%20351%20351-3384>
GPG: B2F3C15F



___
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/


--
Fridolin SOMERS
Biblibre - Pôles support et système
fridolin.som...@biblibre.com
___
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/

Re: [Koha-devel] Marseille16 / REST api

[Tomas Cohen Arazi]

El mié., 12 oct. 2016 a las 7:26, David Cook ()
escribió:

> Really curious to see how this plays out!
>
>
>
> I’ve just added parameter validation to a Koha::Object, and while it works
> well enough, I’m hoping for a more generalized solution. I haven’t looked
> at Koha::Exceptions::* yet, but maybe that will help.
>

I don't know how that would work, what bug number is it?


> Peeking at Koha::Exceptions::MissingParameter, I hope that there’s more
> specificity than just “A required parameter is missing”. I’d want to know
> which required parameter is missing.
>
>
>
> Is there a document somewhere saying how to use Koha::Exceptions?
>

Well, we are not baking our own exception system, we are just using
Class::Exception so it is pretty documented!

Look at bug 17425, you will notice when we throw an exception we can add a
message.

Regards!


>
> David Cook
>
> Systems Librarian
>
> Prosentient Systems
>
> 72/330 Wattle St
>
> Ultimo, NSW 2007
>
> Australia
>
>
>
> Office: 02 9212 0899 <02%2092%2012%2008%2099>
>
> Direct: 02 8005 0595 <02%2080%2005%2005%2095>
>
>
>
> *From:* koha-devel-boun...@lists.koha-community.org [mailto:
> koha-devel-boun...@lists.koha-community.org] *On Behalf Of *Tomas Cohen
> Arazi
> *Sent:* Wednesday, 12 October 2016 2:39 AM
> *To:* koha-devel 
> *Subject:* [Koha-devel] Marseille16 / REST api
>
>
>
> During the first couple Hackfest days, Jonathan, Benjamin and I worked on
> a reference implementation of CRUD code for a REST endpoint, so others can
> read it, discuss it and use it as a reference for their own developments.
>
>
>
> We worked on Koha::Cit(y|ies) because it was a really simple class. All
> our work is now on bug 17428.
>
>
>
> The main goals/concepts we tried to apply were:
>
> * Controller class (Koha::REST::V1::Cities) should be as simple as
> possible. No business logic on it. All business logic is expected to be put
> on the Koha::Cit(ies|y) classes. And fully tested.
>
> * All verbs/use cases should be covered by tests
> (t/db_dependent/api/v1/cities.t). We did it, and this file could be used
> (with little adjustments) as the basis for new endpoint tests.
>
> * Heavy use of exceptions. I wouldn't say we heavily use them, but the
> point is that we pass everything to the business object, and catch
> exceptions it might raise. Martin pointed out that he would help us further
> simplify it, making heavier use of the Swagger plugin's facilities.
> Specially on parameters sanity check. More on this tomorrow!
>
> * Koha::Exceptions got per-class files so the exceptions file is more
> manageable. Bug 17425 introduced Koha/Exceptions/Object.pm, and we propose
> that's the way to go (Koha/Exceptions.pm still has Virtualshelves-related
> exceptions that should be moved).
>
> * Make use of Try::Tiny for try/catch blocks. On the process we wrote
> bug 17425, which introduces new exceptions, we added the dependency for
> Try::Tiny (no worries, it is packaged for Jessie/Ubuntu) and Mirko was here
> to validate.
>
> * Moving business-logic to Koha:: namespace and write REST endpoints on
> top of that business objects. We picked a simple object, Koha::Patron(s)
> will be a more complex one of course. This is what Jonathan has been doing,
> and people willing to write REST endpoints should check with him, and
> probably help moving business logic into Koha:: namespace.
>
>
>
> There are several patches on bugzilla introducing endpoints. We will try
> to contact patch authors to help them make their work match this proposed
> 'guidelines'.
>
>
>
> We are sticking to the 'patches speak' approach, so feel free to criticize
> this implementation, to improve it or even provide a counter-proposal. We
> are otherwise moving on, trying to get a functional complete REST api ASAP.
>
>
>
> Thanks!
>
>
>
> Tomas, Jonathan, Benjamin
>
>
>
>
>
>
>
> --
>
> Tomás Cohen Arazi
>
> Theke Solutions (https://theke.io )
> ✆ +54 9351 3513384 <+54%209%20351%20351-3384>
> GPG: B2F3C15F
>
-- 
Tomás Cohen Arazi
Theke Solutions (https://theke.io )
✆ +54 9351 3513384
GPG: B2F3C15F
___
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/

Re: [Koha-devel] Marseille16 / REST api

[David Cook]

Really curious to see how this plays out!

 

I’ve just added parameter validation to a Koha::Object, and while it works well 
enough, I’m hoping for a more generalized solution. I haven’t looked at 
Koha::Exceptions::* yet, but maybe that will help.

 

Peeking at Koha::Exceptions::MissingParameter, I hope that there’s more 
specificity than just “A required parameter is missing”. I’d want to know which 
required parameter is missing. 

 

Is there a document somewhere saying how to use Koha::Exceptions?

 

David Cook

Systems Librarian

Prosentient Systems

72/330 Wattle St

Ultimo, NSW 2007

Australia

 

Office: 02 9212 0899

Direct: 02 8005 0595

 

From: koha-devel-boun...@lists.koha-community.org 
[mailto:koha-devel-boun...@lists.koha-community.org] On Behalf Of Tomas Cohen 
Arazi
Sent: Wednesday, 12 October 2016 2:39 AM
To: koha-devel 
Subject: [Koha-devel] Marseille16 / REST api

 

During the first couple Hackfest days, Jonathan, Benjamin and I worked on a 
reference implementation of CRUD code for a REST endpoint, so others can read 
it, discuss it and use it as a reference for their own developments.

 

We worked on Koha::Cit(y|ies) because it was a really simple class. All our 
work is now on bug 17428.

 

The main goals/concepts we tried to apply were:

* Controller class (Koha::REST::V1::Cities) should be as simple as possible. No 
business logic on it. All business logic is expected to be put on the 
Koha::Cit(ies|y) classes. And fully tested.

* All verbs/use cases should be covered by tests 
(t/db_dependent/api/v1/cities.t). We did it, and this file could be used (with 
little adjustments) as the basis for new endpoint tests.

* Heavy use of exceptions. I wouldn't say we heavily use them, but the point is 
that we pass everything to the business object, and catch exceptions it might 
raise. Martin pointed out that he would help us further simplify it, making 
heavier use of the Swagger plugin's facilities. Specially on parameters sanity 
check. More on this tomorrow!

* Koha::Exceptions got per-class files so the exceptions file is more 
manageable. Bug 17425 introduced Koha/Exceptions/Object.pm, and we propose 
that's the way to go (Koha/Exceptions.pm still has Virtualshelves-related 
exceptions that should be moved).

* Make use of Try::Tiny for try/catch blocks. On the process we wrote bug 
17425, which introduces new exceptions, we added the dependency for Try::Tiny 
(no worries, it is packaged for Jessie/Ubuntu) and Mirko was here to validate.

* Moving business-logic to Koha:: namespace and write REST endpoints on top of 
that business objects. We picked a simple object, Koha::Patron(s) will be a 
more complex one of course. This is what Jonathan has been doing, and people 
willing to write REST endpoints should check with him, and probably help moving 
business logic into Koha:: namespace.

 

There are several patches on bugzilla introducing endpoints. We will try to 
contact patch authors to help them make their work match this proposed 
'guidelines'.

 

We are sticking to the 'patches speak' approach, so feel free to criticize this 
implementation, to improve it or even provide a counter-proposal. We are 
otherwise moving on, trying to get a functional complete REST api ASAP.

 

Thanks!

 

Tomas, Jonathan, Benjamin

 

 

 

-- 

Tomás Cohen Arazi

Theke Solutions (https://theke.io  )
✆ +54 9351 3513384
GPG: B2F3C15F

___
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/