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( output_with_http_headers );
  47 use C4::Output::JSONStream;
  48 use JSON;
  49
  50 our ( $query, $cookie );
  51
  52 sub _output {
  53     my ( $response, $status ) = @_;
  54     binmode STDOUT, ':encoding(UTF-8)';
  55
  56     if ( $query->param( 'callback' ) ) {
  57         output_with_http_headers $query, $cookie, $query->param( 'callback' ) . '(' . $response->output . ');', 'js';
  58     } else {
  59         output_with_http_headers $query, $cookie, $response->output, 'json', $status;
  60     }
  61 }
  62
  63 =head1 METHODS
  64
  65 =head2 init
  66
  67    our ( $query, $response ) = C4::Service->init( %needed_flags );
  68
  69 Initialize the service and check for the permissions in C<%needed_flags>.
  70
  71 Also, check that the user is authorized and has a current session, and return an
  72 'auth' error if not.
  73
  74 init() returns a C<CGI> object and a C<C4::Output::JSONStream>. The latter can
  75 be used for both flat scripts and those that use dispatch(), and should be
  76 passed to C<return_success()>.
  77
  78 =cut
  79
  80 sub init {
  81     my ( $class, %needed_flags ) = @_;
  82
  83     our $query = CGI->new;
  84
  85     my ( $status, $cookie_, $sessionID ) = check_api_auth( $query, \%needed_flags );
  86
  87     our $cookie = $cookie_; # I have no desire to offend the Perl scoping gods
  88
  89     $class->return_error( 'auth', $status ) if ( $status ne 'ok' );
  90
  91     return ( $query, C4::Output::JSONStream->new );
  92 }
  93
  94 =head2 return_error
  95
  96     C4::Service->return_error( $type, $error, %flags );
  97
  98 Exit the script with HTTP status 400, and return a JSON error object.
  99
 100 C<$type> should be a short, lower case code for the generic type of error (such
 101 as 'auth' or 'input').
 102
 103 C<$error> should be a more specific code giving information on the error. If
 104 multiple errors of the same type occurred, they should be joined by '|'; i.e.,
 105 'expired|different_ip'. Information in C<$error> does not need to be
 106 human-readable, as its formatting should be handled by the client.
 107
 108 Any additional information to be given in the response should be passed as
 109 param => value pairs.
 110
 111 =cut
 112
 113 sub return_error {
 114     my ( $class, $type, $error, %flags ) = @_;
 115
 116     my $response = C4::Output::JSONStream->new;
 117
 118     $response->param( message => $error ) if ( $error );
 119     $response->param( type => $type, %flags );
 120
 121     _output( $response, '400 Bad Request' );
 122     exit;
 123 }
 124
 125 =head2 return_multi
 126
 127     C4::Service->return_multi( \@responses, %flags );
 128
 129 return_multi is similar to return_success or return_error, but allows you to
 130 return different statuses for several requests sent at once (using HTTP status
 131 "207 Multi-Status", much like WebDAV). The toplevel hashref (turned into the
 132 JSON response) looks something like this:
 133
 134     { multi => JSON::true, responses => \@responses, %flags }
 135
 136 Each element of @responses should be either a plain hashref or an arrayref. If
 137 it is a hashref, it is sent to the browser as-is. If it is an arrayref, it is
 138 assumed to be in the same form as the arguments to return_error, and is turned
 139 into an error structure.
 140
 141 All key-value pairs %flags are, as stated above, put into the returned JSON
 142 structure verbatim.
 143
 144 =cut
 145
 146 sub return_multi {
 147     my ( $class, $responses, @flags ) = @_;
 148
 149     my $response = C4::Output::JSONStream->new;
 150
 151     if ( !@$responses ) {
 152         $class->return_success( $response );
 153     } else {
 154         my @responses_formatted;
 155
 156         foreach my $response ( @$responses ) {
 157             if ( ref( $response ) eq 'ARRAY' ) {
 158                 my ($type, $error, @error_flags) = @$response;
 159
 160                 push @responses_formatted, { is_error => JSON::true, type => $type, message => $error, @error_flags };
 161             } else {
 162                 push @responses_formatted, $response;
 163             }
 164         }
 165
 166         $response->param( 'multi' => JSON::true, responses => \@responses_formatted, @flags );
 167         _output( $response, '207 Multi-Status' );
 168     }
 169
 170     exit;
 171 }
 172
 173 =head2 return_success
 174
 175     C4::Service->return_success( $response );
 176
 177 Print out the information in the C<C4::Output::JSONStream> C<$response>, then
 178 exit with HTTP status 200.
 179
 180 =cut
 181
 182 sub return_success {
 183     my ( $class, $response ) = @_;
 184
 185     _output( $response );
 186 }
 187
 188 =head2 require_params
 189
 190     my @values = C4::Service->require_params( @params );
 191
 192 Check that each of of the parameters specified in @params was sent in the
 193 request, then return their values in that order.
 194
 195 If a required parameter is not found, send a 'param' error to the browser.
 196
 197 =cut
 198
 199 sub require_params {
 200     my ( $class, @params ) = @_;
 201
 202     my @values;
 203
 204     for my $param ( @params ) {
 205         $class->return_error( 'params', "Missing '$param'" ) if ( !defined( $query->param( $param ) ) );
 206         push @values, scalar $query->param( $param ); # will we ever need multi_param here?
 207     }
 208
 209     return @values;
 210 }
 211
 212 =head2 dispatch
 213
 214     C4::Service->dispatch(
 215         [ $path_regex, \@required_params, \&handler ],
 216         ...
 217     );
 218
 219 dispatch takes several array-refs, each one describing a 'route', to use the
 220 Rails terminology.
 221
 222 $path_regex should be a string in regex-form, describing which methods and
 223 paths this route handles. Each route is tested in order, from the top down, so
 224 put more specific handlers first. Also, the regex is tested on the request
 225 method, plus the path. For instance, you might use the route [ 'POST /', ... ]
 226 to handle POST requests to your service.
 227
 228 Each named parameter in @required_params is tested for to make sure the route
 229 matches, but does not raise an error if one is missing; it simply tests the next
 230 route. If you would prefer to raise an error, instead use
 231 C<C4::Service->require_params> inside your handler.
 232
 233 \&handler is called with each matched group in $path_regex in its arguments. For
 234 example, if your service is accessed at the path /blah/123, and you call
 235 C<dispatch> with the route [ 'GET /blah/(\\d+)', ... ], your handler will be called
 236 with the argument '123'.
 237
 238 =cut
 239
 240 sub dispatch {
 241     my $class = shift;
 242
 243     my $path_info = $query->path_info || '/';
 244
 245     ROUTE: foreach my $route ( @_ ) {
 246         my ( $path, $params, $handler ) = @$route;
 247
 248         next unless ( my @match = ( ($query->request_method . ' ' . $path_info)   =~ m,^$path$, ) );
 249
 250         for my $param ( @$params ) {
 251             next ROUTE if ( !defined( $query->param ( $param ) ) );
 252         }
 253
 254         $handler->( @match );
 255         return;
 256     }
 257
 258     $class->return_error( 'no_handler', '' );
 259 }
 260
 261 1;
 262
 263 __END__
 264
 265 =head1 AUTHORS
 266
 267 Koha Development Team
 268
 269 Jesse Weaver <jesse.weaver@liblime.com>