Main Koha release repository
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

276 lines
7.5 KiB

package C4::Service;
# Copyright 2008 LibLime
# This file is part of Koha.
# Koha is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.
# Koha is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with Koha; if not, see <>.
=head1 NAME
C4::Service - functions for JSON webservices.
my ( $query, $response) = C4::Service->init( { circulate => 1 } );
my ( $borrowernumber) = C4::Service->require_params( 'borrowernumber' );
C4::Service->return_error( 'internal', 'Frobnication failed', frobnicator => 'foo' );
$response->param( frobnicated => 'You' );
C4::Service->return_success( $response );
This module packages several useful functions for JSON webservices.
use strict;
use warnings;
use CGI qw ( -utf8 );
use C4::Auth qw( check_api_auth );
use C4::Output qw( :ajax );
use C4::Output::JSONStream;
use JSON;
our $debug;
$debug = $ENV{DEBUG} || 0;
our ( $query, $cookie );
sub _output {
my ( $response, $status ) = @_;
binmode STDOUT, ':encoding(UTF-8)';
if ( $query->param( 'callback' ) ) {
output_with_http_headers $query, $cookie, $query->param( 'callback' ) . '(' . $response->output . ');', 'js';
} else {
output_with_http_headers $query, $cookie, $response->output, 'json', $status;
=head1 METHODS
=head2 init
our ( $query, $response ) = C4::Service->init( %needed_flags );
Initialize the service and check for the permissions in C<%needed_flags>.
Also, check that the user is authorized and has a current session, and return an
'auth' error if not.
init() returns a C<CGI> object and a C<C4::Output::JSONStream>. The latter can
be used for both flat scripts and those that use dispatch(), and should be
passed to C<return_success()>.
sub init {
my ( $class, %needed_flags ) = @_;
our $query = CGI->new;
my ( $status, $cookie_, $sessionID ) = check_api_auth( $query, \%needed_flags );
our $cookie = $cookie_; # I have no desire to offend the Perl scoping gods
$class->return_error( 'auth', $status ) if ( $status ne 'ok' );
return ( $query, C4::Output::JSONStream->new );
=head2 return_error
C4::Service->return_error( $type, $error, %flags );
Exit the script with HTTP status 400, and return a JSON error object.
C<$type> should be a short, lower case code for the generic type of error (such
as 'auth' or 'input').
C<$error> should be a more specific code giving information on the error. If
multiple errors of the same type occurred, they should be joined by '|'; i.e.,
'expired|different_ip'. Information in C<$error> does not need to be
human-readable, as its formatting should be handled by the client.
Any additional information to be given in the response should be passed as
param => value pairs.
sub return_error {
my ( $class, $type, $error, %flags ) = @_;
my $response = C4::Output::JSONStream->new;
$response->param( message => $error ) if ( $error );
$response->param( type => $type, %flags );
_output( $response, '400 Bad Request' );
=head2 return_multi
C4::Service->return_multi( \@responses, %flags );
return_multi is similar to return_success or return_error, but allows you to
return different statuses for several requests sent at once (using HTTP status
"207 Multi-Status", much like WebDAV). The toplevel hashref (turned into the
JSON response) looks something like this:
{ multi => JSON::true, responses => \@responses, %flags }
Each element of @responses should be either a plain hashref or an arrayref. If
it is a hashref, it is sent to the browser as-is. If it is an arrayref, it is
assumed to be in the same form as the arguments to return_error, and is turned
into an error structure.
All key-value pairs %flags are, as stated above, put into the returned JSON
structure verbatim.
sub return_multi {
my ( $class, $responses, @flags ) = @_;
my $response = C4::Output::JSONStream->new;
if ( !@$responses ) {
$class->return_success( $response );
} else {
my @responses_formatted;
foreach my $response ( @$responses ) {
if ( ref( $response ) eq 'ARRAY' ) {
my ($type, $error, @error_flags) = @$response;
push @responses_formatted, { is_error => JSON::true, type => $type, message => $error, @error_flags };
} else {
push @responses_formatted, $response;
$response->param( 'multi' => JSON::true, responses => \@responses_formatted, @flags );
_output( $response, '207 Multi-Status' );
=head2 return_success
C4::Service->return_success( $response );
Print out the information in the C<C4::Output::JSONStream> C<$response>, then
exit with HTTP status 200.
sub return_success {
my ( $class, $response ) = @_;
_output( $response );
=head2 require_params
my @values = C4::Service->require_params( @params );
Check that each of of the parameters specified in @params was sent in the
request, then return their values in that order.
If a required parameter is not found, send a 'param' error to the browser.
sub require_params {
my ( $class, @params ) = @_;
my @values;
for my $param ( @params ) {
$class->return_error( 'params', "Missing '$param'" ) if ( !defined( $query->param( $param ) ) );
push @values, scalar $query->param( $param ); # will we ever need multi_param here?
return @values;
=head2 dispatch
[ $path_regex, \@required_params, \&handler ],
dispatch takes several array-refs, each one describing a 'route', to use the
Rails terminology.
$path_regex should be a string in regex-form, describing which methods and
paths this route handles. Each route is tested in order, from the top down, so
put more specific handlers first. Also, the regex is tested on the request
method, plus the path. For instance, you might use the route [ 'POST /', ... ]
to handle POST requests to your service.
Each named parameter in @required_params is tested for to make sure the route
matches, but does not raise an error if one is missing; it simply tests the next
route. If you would prefer to raise an error, instead use
C<C4::Service->require_params> inside your handler.
\&handler is called with each matched group in $path_regex in its arguments. For
example, if your service is accessed at the path /blah/123, and you call
C<dispatch> with the route [ 'GET /blah/(\\d+)', ... ], your handler will be called
with the argument '123'.
sub dispatch {
my $class = shift;
my $path_info = $query->path_info || '/';
ROUTE: foreach my $route ( @_ ) {
my ( $path, $params, $handler ) = @$route;
next unless ( my @match = ( ($query->request_method . ' ' . $path_info) =~ m,^$path$, ) );
for my $param ( @$params ) {
next ROUTE if ( !defined( $query->param ( $param ) ) );
$debug and warn "Using $path";
$handler->( @match );
$class->return_error( 'no_handler', '' );
=head1 AUTHORS
Koha Development Team
Jesse Weaver <>