From 1920b96744bcdd4c4266fc54e316c63aacdd72dc Mon Sep 17 00:00:00 2001 From: Julian Maurice Date: Wed, 4 Mar 2015 16:46:33 +0100 Subject: [PATCH] Bug 13799: 1. RESTful API with Mojolicious and Swagger2 Actual routes are: /borrowers Return a list of all borrowers in Koha /borrowers/{borrowernumber} Return the borrower identified by {borrowernumber} (eg. /borrowers/1) There is a test file you can run with: $ prove t/db_dependent/rest/borrowers.t All API stuff is in /api/v1 (except Perl modules) So we have: /api/v1/script.cgi CGI script /api/v1/swagger.json Swagger specification Add a virtual host in Apache configuration api.HOSTNAME So we have: http://api.HOSTNAME/v1/swagger.json Swagger specification http://api.HOSTNAME/v1/{path} API endpoint Add 'unblessed' subroutines to both Koha::Objects and Koha::Object to be able to pass it to Mojolicious Test plan: 1/ Install Perl modules Mojolicious and Swagger2 2/ perl Makefile.PL 3/ make && make install 4/ Change etc/koha-httpd.conf and copy it to the right place if needed 5/ Reload Apache 6/ Check that http://api.HOSTNAME/v1/borrowers and http://api.HOSTNAME/v1/borrowers/{borrowernumber} works Optionally, you could verify that http://api.HOSTNAME/vX/borrowers (where X is an integer greater than 1) returns a 404 error For the new vhost to work, you may need to modify your /etc/hosts file if you run Koha locally. --- C4/Installer/PerlDependencies.pm | 10 ++++ Koha/Object.pm | 12 +++++ Koha/Objects.pm | 12 +++++ Koha/REST/V1.pm | 25 +++++++++ Koha/REST/V1/Borrowers.pm | 29 ++++++++++ api/v1/script.cgi | 6 +++ api/v1/swagger.json | 108 ++++++++++++++++++++++++++++++++++++++ etc/koha-httpd.conf | 19 +++++++ t/db_dependent/api/v1/borrowers.t | 37 +++++++++++++ 9 files changed, 258 insertions(+) create mode 100644 Koha/REST/V1.pm create mode 100644 Koha/REST/V1/Borrowers.pm create mode 100644 api/v1/script.cgi create mode 100644 api/v1/swagger.json create mode 100644 t/db_dependent/api/v1/borrowers.t diff --git a/C4/Installer/PerlDependencies.pm b/C4/Installer/PerlDependencies.pm index 6911b4b..3b6deb9 100644 --- a/C4/Installer/PerlDependencies.pm +++ b/C4/Installer/PerlDependencies.pm @@ -767,6 +767,16 @@ our $PERL_DEPS = { 'required' => '0', 'min_ver' => '0.0.3', }, + 'Mojolicious' => { + 'usage' => 'REST API', + 'required' => '0', + 'min_ver' => '5.54', + }, + 'Swagger2' => { + 'usage' => 'REST API', + 'required' => '0', + 'min_ver' => '0.28', + }, }; 1; diff --git a/Koha/Object.pm b/Koha/Object.pm index a77eb5c..6e53461 100644 --- a/Koha/Object.pm +++ b/Koha/Object.pm @@ -207,6 +207,18 @@ sub id { return $id; } +=head3 $object->unblessed(); + +Returns an unblessed representation of object. + +=cut + +sub unblessed { + my ($self) = @_; + + return { $self->_result->get_columns }; +} + =head3 $object->_result(); Returns the internal DBIC Row object diff --git a/Koha/Objects.pm b/Koha/Objects.pm index f490549..7487a91 100644 --- a/Koha/Objects.pm +++ b/Koha/Objects.pm @@ -310,6 +310,18 @@ sub as_list { return wantarray ? @objects : \@objects; } +=head3 Koha::Objects->unblessed + +Returns an unblessed representation of objects. + +=cut + +sub unblessed { + my ($self) = @_; + + return [ map { $_->unblessed } $self->as_list ]; +} + =head3 Koha::Objects->_wrap wraps the DBIC object in a corresponding Koha object diff --git a/Koha/REST/V1.pm b/Koha/REST/V1.pm new file mode 100644 index 0000000..3becf12 --- /dev/null +++ b/Koha/REST/V1.pm @@ -0,0 +1,25 @@ +package Koha::REST::V1; + +use Modern::Perl; +use Mojo::Base 'Mojolicious'; + +sub startup { + my $self = shift; + + my $route = $self->routes->under->to( + cb => sub { + my $c = shift; + my $user = $c->param('user'); + # Do the authentication stuff here... + $c->stash('user', $user); + return 1; + } + ); + + $self->plugin(Swagger2 => { + route => $route, + url => $self->home->rel_file("api/v1/swagger.json"), + }); +} + +1; diff --git a/Koha/REST/V1/Borrowers.pm b/Koha/REST/V1/Borrowers.pm new file mode 100644 index 0000000..b58ad2a --- /dev/null +++ b/Koha/REST/V1/Borrowers.pm @@ -0,0 +1,29 @@ +package Koha::REST::V1::Borrowers; + +use Modern::Perl; + +use Mojo::Base 'Mojolicious::Controller'; + +use Koha::Borrowers; + +sub list_borrowers { + my ($c, $args, $cb) = @_; + + my $borrowers = Koha::Borrowers->search; + + $c->$cb($borrowers->unblessed, 200); +} + +sub get_borrower { + my ($c, $args, $cb) = @_; + + my $borrower = Koha::Borrowers->find($args->{borrowernumber}); + + if ($borrower) { + return $c->$cb($borrower->unblessed, 200); + } + + $c->$cb({error => "Borrower not found"}, 404); +} + +1; diff --git a/api/v1/script.cgi b/api/v1/script.cgi new file mode 100644 index 0000000..55ce87d --- /dev/null +++ b/api/v1/script.cgi @@ -0,0 +1,6 @@ +#!/usr/bin/env perl + +use Modern::Perl; + +require Mojolicious::Commands; +Mojolicious::Commands->start_app('Koha::REST::V1'); diff --git a/api/v1/swagger.json b/api/v1/swagger.json new file mode 100644 index 0000000..5e97d03 --- /dev/null +++ b/api/v1/swagger.json @@ -0,0 +1,108 @@ +{ + "swagger": "2.0", + "info": { + "title": "Koha REST API", + "version": "1", + "license": { + "name": "GPL v3", + "url": "http://www.gnu.org/licenses/gpl.txt" + }, + "contact": { + "name": "Koha Team", + "url": "http://koha-community.org/" + } + }, + "basePath": "/v1", + "paths": { + "/borrowers": { + "get": { + "x-mojo-controller": "Koha::REST::V1::Borrowers", + "operationId": "listBorrowers", + "tags": ["borrowers"], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "A list of borrowers", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/borrower" + } + } + } + } + } + }, + "/borrowers/{borrowernumber}": { + "get": { + "x-mojo-controller": "Koha::REST::V1::Borrowers", + "operationId": "getBorrower", + "tags": ["borrowers"], + "parameters": [ + { + "$ref": "#/parameters/borrowernumberPathParam" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "A borrower", + "schema": { + "$ref": "#/definitions/borrower" + } + }, + "404": { + "description": "Borrower not found", + "schema": { + "$ref": "#/definitions/error" + } + } + } + } + } + }, + "definitions": { + "borrower": { + "type": "object", + "properties": { + "borrowernumber": { + "$ref": "#/definitions/borrowernumber" + }, + "cardnumber": { + "description": "library assigned ID number for borrowers" + }, + "surname": { + "description": "borrower's last name" + }, + "firstname": { + "description": "borrower's first name" + } + } + }, + "borrowernumber": { + "description": "Borrower internal identifier" + }, + "error": { + "type": "object", + "properties": { + "error": { + "description": "Error message", + "type": "string" + } + } + } + }, + "parameters": { + "borrowernumberPathParam": { + "name": "borrowernumber", + "in": "path", + "description": "Internal borrower identifier", + "required": "true", + "type": "integer" + } + } +} diff --git a/etc/koha-httpd.conf b/etc/koha-httpd.conf index f9a1970..000e94a 100644 --- a/etc/koha-httpd.conf +++ b/etc/koha-httpd.conf @@ -216,3 +216,22 @@ RewriteRule ^/issn/([^\/]*)/?$ /search?q=issn:$1 [PT] + + + ServerAdmin __WEBMASTER_EMAIL__ + DocumentRoot __INTRANET_CGI_DIR__/api + ServerName api.__WEBSERVER_HOST__:__WEBSERVER_PORT__ + SetEnv KOHA_CONF "__KOHA_CONF_DIR__/koha-conf.xml" + SetEnv PERL5LIB "__PERL_MODULE_DIR__" + + + Options +ExecCGI +FollowSymlinks + AddHandler cgi-script .cgi + + RewriteEngine on + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteCond %{DOCUMENT_ROOT}/$1/script.cgi -f + RewriteRule ^(.*?)/.* $1/script.cgi/$0 [L] + + diff --git a/t/db_dependent/api/v1/borrowers.t b/t/db_dependent/api/v1/borrowers.t new file mode 100644 index 0000000..a86887b --- /dev/null +++ b/t/db_dependent/api/v1/borrowers.t @@ -0,0 +1,37 @@ +#!/usr/bin/env perl + +use Modern::Perl; + +use Test::More tests => 6; +use Test::Mojo; + +use C4::Context; + +use Koha::Database; +use Koha::Borrower; + +my $dbh = C4::Context->dbh; +$dbh->{AutoCommit} = 0; +$dbh->{RaiseError} = 1; + +my $t = Test::Mojo->new('Koha::REST::V1'); + +my $categorycode = Koha::Database->new()->schema()->resultset('Category')->first()->categorycode(); +my $branchcode = Koha::Database->new()->schema()->resultset('Branch')->first()->branchcode(); + +my $borrower = Koha::Borrower->new; +$borrower->categorycode( $categorycode ); +$borrower->branchcode( $branchcode ); +$borrower->surname("Test Surname"); +$borrower->store; +my $borrowernumber = $borrower->borrowernumber; + +$t->get_ok('/v1/borrowers') + ->status_is(200); + +$t->get_ok("/v1/borrowers/$borrowernumber") + ->status_is(200) + ->json_is('/borrowernumber' => $borrowernumber) + ->json_is('/surname' => "Test Surname"); + +$dbh->rollback; -- 1.9.1