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.
our ( $query, $response ) = C4::Service->init( %needed_flags );
Initialize the service and check for the permissions in %needed_flags.
Also, check that the user is authorized and has a current session, and return an 'auth' error if not.
init() returns a CGI object and a C4::Output::JSONStream. The latter can be used for both flat scripts and those that use dispatch(), and should be passed to return_success().
C4::Service->return_error( $type, $error, %flags );
Exit the script with HTTP status 400, and return a JSON error object.
$type should be a short, lower case code for the generic type of error (such as 'auth' or 'input').
$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 $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.
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.
C4::Service->return_success( $response );
Print out the information in the C4::Output::JSONStream $response, then exit with HTTP status 200.
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.
C4::Service->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 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 dispatch with the route [ 'GET /blah/(\\d+)', ... ], your handler will be called with the argument '123'.
Koha Development Team
Jesse Weaver <jesse.weaver@liblime.com>