El lun., 20 de mayo de 2019 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