[Koha-devel] Restful API question
Tomas Cohen Arazi
tomascohen at gmail.com
Mon May 20 17:25:54 CEST 2019
The _to_api method is required in patrons endpoint, only because we don't
want to expose exactly the same attribute names as the DB columns and some
others are just generated.
So you need to make the objects match your spec.
El lun., 20 de mayo de 2019 11:40, Stephen Graham <s.graham4 at herts.ac.uk>
escribió:
> Hi Tomas – the ability to extend the API with custom endpoints using the
> plugin system is a great Koha feature! 😊
>
>
>
> If I change my openapi.json to what you suggest I get:
>
>
>
> {"errors":[{"message":"Expected array - got
> string.","path":"\/"}],"status":500}
>
>
>
> , so I guess I need to pass my data to the render method as an array and
> not as a JSON string? If I do this I’m getting a can’t call method on
> unblessed refence error:
>
>
>
> my @n = map { ( $_->encode_json ) } @{$notices};
>
> return $c->render( status => 200, openapi => \@n );
>
>
>
> I guess because @{$notices} is an array of hashes? I see in the Patrons.pm
> REST module, that they are using a method called _*to*_api, which
> according to the Perl doc:
>
>
>
> “Helper function that maps unblessed Koha::Patron objects into REST api
> attribute names.”
>
>
>
> Sorry, it might be obvious, but do I need to iterate though my results and
> convert them into…. I’m not sure what really. Looking at the _*to*_api
> method it just seems to be mapping the database column names to the API
> names, which I have done already in my initial sql query, and returns a
> Patron object. Should I be able to do what I want with the data structure I
> get from a fetchall_arrayref({})?
>
>
>
> Cheers, Stephen
>
>
>
>
>
> *From:* Tomas Cohen Arazi <tomascohen at gmail.com>
> *Sent:* 20 May 2019 14:25
> *To:* Stephen Graham <s.graham4 at herts.ac.uk>
> *Cc:* koha-devel <koha-devel at lists.koha-community.org>
> *Subject:* Re: [Koha-devel] Restful API question
>
>
>
> I think it should read like:
>
> "200": {
> "description": "A list pending notifications",
> "schema": {
> "type": "array",
> "items": {
> "type": "object",
> "properties": {
> "userid": {
> "type": "string",
> "description": "Unique User ID"
> },
> ...
> }
> }
> }
> }
>
> You can of course under-specify it, just saying you return JSON or the way
> you did it, just avoiding OpenAPI altogether, but you loose the ability for
> consumers to have a well documented API, and also you loose data validation
> (in and out), which is very important when implementing the API.
>
>
>
> Happy to see others playing with this! Let me know how can I help1
>
>
>
> El lun., 20 may. 2019 a las 10:05, Stephen Graham (<s.graham4 at herts.ac.uk>)
> escribió:
> >
> > Hi Tomas – the below is what I have. When I do my sql select I’m doing:
> >
> >
> >
> > select b.userid as userid,
> >
> > mq.message_id as messageid,
> >
> > mq.subject as subject,
> >
> > mq.content as body
> >
> >
> >
> > ,so the field names should map to the item names in the openapi.json.
> I’m just not sure what I should be passing to the render method, and how to
> describe that in the openapi.json file. At the moment I’m passing a string
> – it’s JSON – but just a string. Maybe that isn’t right? When I look to see
> how the Patrons API does it, it works like:
> >
> >
> >
> > my @patrons = $patrons->as_list;
> >
> > @patrons = map { _to_api( $_->TO_JSON ) } @patrons;
> >
> > return $c->render( status => 200, openapi => \@patrons );
> >
> >
> >
> > and then seems to say it’s an array of objects in their json files
> (patron.json and patron.json).
> >
> >
> >
> > Here is my openapi.json file:
> >
> >
> >
> > {
> >
> > "/notifications": {
> >
> > "get": {
> >
> > "x-mojo-to":
> "Uk::Ac::Herts::Notifications::NotificationController#getPendingNotices",
> >
> > "operationId": "PatronEmailNotice",
> >
> > "tags": ["notifications"],
> >
> > "produces": [
> >
> > "application/json"
> >
> > ],
> >
> > "responses": {
> >
> > "200": {
> >
> > "description": "A list of pending notices",
> >
> > "schema": {
> >
> > "type": "array",
> >
> > "items": {
> >
> > "userid": {
> >
> > "type": "string",
> >
> > "description": "Unique User ID"
> >
> > },
> >
> > "messageid": {
> >
> > "type": "string",
> >
> > "description": "Unique Notice ID"
> >
> > },
> >
> > "subject": {
> >
> > "type": "string",
> >
> > "description": "Notice Subject"
> >
> > },
> >
> > "body": {
> >
> > "type": "string",
> >
> > "description": "Notice Body"
> >
> > }
> >
> > }
> >
> > }
> >
> > },
> >
> > "404": {
> >
> > "description": "An error occured",
> >
> > "schema": {
> >
> > "type": "object",
> >
> > "properties": {
> >
> > "error": {
> >
> > "description": "An explanation for the error",
> >
> > "type": "string"
> >
> > }
> >
> > }
> >
> > }
> >
> > }
> >
> > },
> >
> > "x-koha-authorization": {
> >
> > "permissions": {
> >
> > "borrowers": "1"
> >
> > }
> >
> > }
> >
> > }
> >
> > }
> >
> > }
> >
> >
> >
> > From: Tomas Cohen Arazi <tomascohen at gmail.com>
> > Sent: 20 May 2019 12:28
> > To: Stephen Graham <s.graham4 at herts.ac.uk>
> > Cc: koha-devel <koha-devel at lists.koha-community.org>
> > Subject: Re: [Koha-devel] Restful API question
> >
> >
> >
> > The most probable problem is the OpenAPI spec is wrong, and then the
> plugin API is skipped altogether.
> >
> >
> >
> > If possible, share the openapi.json file in your plugin
> >
> >
> >
> > El lun., 20 de mayo de 2019 08:18, Stephen Graham <s.graham4 at herts.ac.uk>
> escribió:
> >
> > Hi all – I know it’s Kohacon this week so a lot of people will be busy
> there, but just in case ……… (also sorry for the length of the email!):
> >
> >
> >
> > I testing creating a custom API endpoint using the Koha plugin system.
> I’ve been using the code in the Kitchen sink plugin as a template, and it
> seems to be working well apart from my lack of Swagger/OpenAPI knowledge –
> I think it’s this I struggling with. I have three files:
> >
> >
> >
> > koha-dev/var/lib/plugins/Koha/Plugin/Uk/Ac/Herts/Notifications.pm
> >
> >
> koha-dev/var/lib/plugins/Koha/Plugin/Uk/Ac/Herts/Notifications/NotificationController.pm
> >
> >
> koha-dev/var/lib/plugins/Koha/Plugin/Uk/Ac/Herts/Notifications/openapi.json
> >
> >
> >
> > The work is done in NotificationController.pm where I have a DBI call to
> get the following fields:
> >
> >
> >
> > Borrower.userid
> >
> > Message_queue.message_id
> >
> > Message_queue.subject
> >
> > Message_queue.content
> >
> >
> >
> > I fetch the data, and convert into JSON (encode_json is a method from
> Mojo::JSON) like:
> >
> >
> >
> > my $data = $sth->fetchall_arrayref({}); # return both fieldnames and
> values
> >
> > my $json = encode_json($data);
> >
> >
> >
> > if I then do (i.e. use text):
> >
> >
> >
> > return $c->render( status => 200, text => $json)
> >
> >
> >
> > it works fine. If I call
> https://herttest-staff.koha-ptfs.co.uk/api/v1/contrib/UH/notifications I
> get json like:
> >
> >
> >
> > [ {
> >
> > “body”: “blah blah”,
> >
> > “messageid”: “1234567”,
> >
> > “subject”: “Important…”,
> >
> > “userid”: 99999999”
> >
> > } {
> >
> > Etc etc
> >
> > }]
> >
> >
> >
> > So in Perl terms it’s an array of hashes. Which is what I want. However,
> if I try and use the openapi way that all the current “official” Koha
> endpoints use e.g.
> >
> >
> >
> > return $c->render( status => 200, openapi => { notices => $json } );
> >
> >
> >
> > it just doesn’t work. I have tried to map the field names with the
> appropriate types in openapi.json. I’ve tried object type with properties
> e.g.
> >
> >
> >
> > "responses": {
> >
> > "200": {
> >
> > "description": "A list of pending notices",
> >
> > "schema": {
> >
> > "type": "object",
> >
> > "properties": {
> >
> > "userid": {
> >
> > "type": "string",
> >
> > "description": "Unique User ID"
> >
> > }, etc
> >
> >
> >
> > , and I’ve tried array type with items:
> >
> >
> >
> > "responses": {
> >
> > "200": {
> >
> > "description": "A list of pending notices",
> >
> > "schema": {
> >
> > "type": "array",
> >
> > "items": {
> >
> > "userid": {
> >
> > "type": "string",
> >
> > "description": "Unique User ID"
> >
> > }, etc
> >
> >
> >
> > But I get a page not found error. When I pass my $json variable to the
> render method using openapi how do I get it to work? I’m happy to use the
> text way, but I want to understand where I’m going wrong. Any ideas, hints,
> tips would be most welcome!
> >
> >
> >
> > Cheers, Stephen
> >
> >
> >
> > --------------------------------------
> >
> > Stephen Graham
> >
> > Library Technology Consultant
> >
> > Content and Collections Team
> >
> > Library and Computing Services
> >
> > University of Hertfordshire
> >
> > Tel: 01707 286111
> >
> > Ext: 77751
> >
> > Email: s.graham4 at herts.ac.uk
> >
> >
> >
> > _______________________________________________
> > Koha-devel mailing list
> > Koha-devel at lists.koha-community.org
> > http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
> > website : http://www.koha-community.org/
> > git : http://git.koha-community.org/
> > bugs : http://bugs.koha-community.org/
>
>
>
> --
> Tomás Cohen Arazi
> Theke Solutions (http://theke.io)
> ✆ +54 9351 3513384
> GPG: B2F3C15F
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20190520/7db74021/attachment-0001.html>
More information about the Koha-devel
mailing list