[Koha-devel] Restful API question

20 May 2019

      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<mailto:s.graham4@herts.ac.uk>