C4/Service.pm

   1 package C4::Service;
   2 #
   3 # Copyright 2008 LibLime
   4 #
   5 # This file is part of Koha.
   6 #
   7 # Koha is free software; you can redistribute it and/or modify it
   8 # under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 3 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but
  13 # WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  19
  20 =head1 NAME
  21
  22 C4::Service - functions for JSON webservices.
  23
  24 =head1 SYNOPSIS
  25
  26 my ( $query, $response) = C4::Service->init( { circulate => 1 } );
  27 my ( $borrowernumber) = C4::Service->require_params( 'borrowernumber' );
  28
  29 C4::Service->return_error( 'internal', 'Frobnication failed', frobnicator => 'foo' );
  30
  31 $response->param( frobnicated => 'You' );
  32
  33 C4::Service->return_success( $response );
  34
  35 =head1 DESCRIPTION
  36
  37 This module packages several useful functions for JSON webservices.
  38
  39 =cut
  40
  41 use strict;
  42 use warnings;
  43
  44 use CGI qw ( -utf8 );
  45 use C4::Auth qw( check_api_auth );
  46 use C4::Output qw( :ajax );
  47 use C4::Output::JSONStream;
  48 use JSON;
  49
  50 our $debug;
  51
  52 BEGIN {
  53     $debug = $ENV{DEBUG} || 0;
  54 }
  55
  56 our ( $query, $cookie );
  57
  58 =head1 METHODS
  59
  60 =head2 init
  61
  62    our ( $query, $response ) = C4::Service->init( %needed_flags );
  63
  64 Initialize the service and check for the permissions in C<%needed_flags>.
  65
  66 Also, check that the user is authorized and has a current session, and return an
  67 'auth' error if not.
  68
  69 init() returns a C<CGI> object and a C<C4::Output::JSONStream>. The latter can
  70 be used for both flat scripts and those that use dispatch(), and should be
  71 passed to C<return_success()>.
  72
  73 =cut
  74
  75 sub init {
  76     my ( $class, %needed_flags ) = @_;
  77
  78     our $query = new CGI;
  79
  80     my ( $status, $cookie_, $sessionID ) = check_api_auth( $query, \%needed_flags );
  81
  82     our $cookie = $cookie_; # I have no desire to offend the Perl scoping gods
  83
  84     $class->return_error( 'auth', $status ) if ( $status ne 'ok' );
  85
  86     return ( $query, new C4::Output::JSONStream );
  87 }
  88
  89 =head2 return_error
  90
  91     C4::Service->return_error( $type, $error, %flags );
  92
  93 Exit the script with HTTP status 400, and return a JSON error object.
  94
  95 C<$type> should be a short, lower case code for the generic type of error (such
  96 as 'auth' or 'input').
  97
  98 C<$error> should be a more specific code giving information on the error. If
  99 multiple errors of the same type occurred, they should be joined by '|'; i.e.,
 100 'expired|different_ip'. Information in C<$error> does not need to be
 101 human-readable, as its formatting should be handled by the client.
 102
 103 Any additional information to be given in the response should be passed as
 104 param => value pairs.
 105
 106 =cut
 107
 108 sub return_error {
 109     my ( $class, $type, $error, %flags ) = @_;
 110
 111     my $response = new C4::Output::JSONStream;
 112
 113     $response->param( message => $error ) if ( $error );
 114     $response->param( type => $type, %flags );
 115
 116     output_with_http_headers $query, $cookie, $response->output, 'json', '400 Bad Request';
 117     exit;
 118 }
 119
 120 =head2 return_multi
 121
 122     C4::Service->return_multi( \@responses, %flags );
 123
 124 return_multi is similar to return_success or return_error, but allows you to
 125 return different statuses for several requests sent at once (using HTTP status
 126 "207 Multi-Status", much like WebDAV). The toplevel hashref (turned into the
 127 JSON response) looks something like this:
 128
 129     { multi => JSON::true, responses => \@responses, %flags }
 130
 131 Each element of @responses should be either a plain hashref or an arrayref. If
 132 it is a hashref, it is sent to the browser as-is. If it is an arrayref, it is
 133 assumed to be in the same form as the arguments to return_error, and is turned
 134 into an error structure.
 135
 136 All key-value pairs %flags are, as stated above, put into the returned JSON
 137 structure verbatim.
 138
 139 =cut
 140
 141 sub return_multi {
 142     my ( $class, $responses, @flags ) = @_;
 143
 144     my $response = new C4::Output::JSONStream;
 145
 146     if ( !@$responses ) {
 147         $class->return_success( $response );
 148     } else {
 149         my @responses_formatted;
 150
 151         foreach my $response ( @$responses ) {
 152             if ( ref( $response ) eq 'ARRAY' ) {
 153                 my ($type, $error, @error_flags) = @$response;
 154
 155                 push @responses_formatted, { is_error => JSON::true, type => $type, message => $error, @error_flags };
 156             } else {
 157                 push @responses_formatted, $response;
 158             }
 159         }
 160
 161         $response->param( 'multi' => JSON::true, responses => \@responses_formatted, @flags );
 162         output_with_http_headers $query, $cookie, $response->output, 'json', '207 Multi-Status';
 163     }
 164
 165     exit;
 166 }
 167
 168 =head2 return_success
 169
 170     C4::Service->return_success( $response );
 171
 172 Print out the information in the C<C4::Output::JSONStream> C<$response>, then
 173 exit with HTTP status 200.
 174
 175 =cut
 176
 177 sub return_success {
 178     my ( $class, $response ) = @_;
 179
 180     output_with_http_headers $query, $cookie, $response->output, 'json';
 181 }
 182
 183 =head2 require_params
 184
 185     my @values = C4::Service->require_params( @params );
 186
 187 Check that each of of the parameters specified in @params was sent in the
 188 request, then return their values in that order.
 189
 190 If a required parameter is not found, send a 'param' error to the browser.
 191
 192 =cut
 193
 194 sub require_params {
 195     my ( $class, @params ) = @_;
 196
 197     my @values;
 198
 199     for my $param ( @params ) {
 200         $class->return_error( 'params', "Missing '$param'" ) if ( !defined( $query->param( $param ) ) );
 201         push @values, $query->param( $param );
 202     }
 203
 204     return @values;
 205 }
 206
 207 =head2 dispatch
 208
 209     C4::Service->dispatch(
 210         [ $path_regex, \@required_params, \&handler ],
 211         ...
 212     );
 213
 214 dispatch takes several array-refs, each one describing a 'route', to use the
 215 Rails terminology.
 216
 217 $path_regex should be a string in regex-form, describing which methods and
 218 paths this route handles. Each route is tested in order, from the top down, so
 219 put more specific handlers first. Also, the regex is tested on the request
 220 method, plus the path. For instance, you might use the route [ 'POST /', ... ]
 221 to handle POST requests to your service.
 222
 223 Each named parameter in @required_params is tested for to make sure the route
 224 matches, but does not raise an error if one is missing; it simply tests the next
 225 route. If you would prefer to raise an error, instead use
 226 C<C4::Service->require_params> inside your handler.
 227
 228 \&handler is called with each matched group in $path_regex in its arguments. For
 229 example, if your service is accessed at the path /blah/123, and you call
 230 C<dispatch> with the route [ 'GET /blah/(\\d+)', ... ], your handler will be called
 231 with the argument '123'.
 232
 233 =cut
 234
 235 sub dispatch {
 236     my $class = shift;
 237
 238     my $path_info = $query->path_info || '/';
 239
 240     ROUTE: foreach my $route ( @_ ) {
 241         my ( $path, $params, $handler ) = @$route;
 242
 243         next unless ( my @match = ( ($query->request_method . ' ' . $path_info)   =~ m,^$path$, ) );
 244
 245         for my $param ( @$params ) {
 246             next ROUTE if ( !defined( $query->param ( $param ) ) );
 247         }
 248
 249         $debug and warn "Using $path";
 250         $handler->( @match );
 251         return;
 252     }
 253
 254     $class->return_error( 'no_handler', '' );
 255 }
 256
 257 1;
 258
 259 __END__
 260
 261 =head1 AUTHORS
 262
 263 Koha Development Team
 264
 265 Jesse Weaver <jesse.weaver@liblime.com>