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