[Koha-devel] Restful API question
Tomas Cohen Arazi
tomascohen at gmail.com
Mon May 20 17:49:41 CEST 2019
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 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
>
--
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/f88db3a6/attachment-0001.html>
More information about the Koha-devel
mailing list