I misread your email while walking :-D You are right, the render call on the OpenAPI plugin requires you to feed it with a data structure that can be rendered as a JSON object. So what I'd loop on the results using fetch_hashref, and then do what is needed on each field (including mapping 1/0 into Mojo::JSON->true/Mojo::JSON->false if boolean, making integers really be integers, etc. El lun., 20 may. 2019 a las 11:40, Stephen Graham (<s.graham4@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@gmail.com> *Sent:* 20 May 2019 14:25 *To:* Stephen Graham <s.graham4@herts.ac.uk> *Cc:* koha-devel <koha-devel@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@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@gmail.com> Sent: 20 May 2019 12:28 To: Stephen Graham <s.graham4@herts.ac.uk> Cc: koha-devel <koha-devel@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@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@herts.ac.uk
_______________________________________________ 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 Theke Solutions (http://theke.io) ✆ +54 9351 3513384 GPG: B2F3C15F
-- Tomás Cohen Arazi Theke Solutions (http://theke.io) ✆ +54 9351 3513384 GPG: B2F3C15F