WebService::ILS - Standardised library discovery/circulation services
use WebService::ILS::<Provider Subclass>; my $ils = WebService::ILS::<Provider Subclass>->new({ client_id => $client_id, client_secret => $client_secret }); my %search_params = ( query => "Some keyword", sort => "rating", ); my $result = $ils->search(\%search_params); foreach (@{ $result->{items} }) { ... } foreach (2..$result->{pages}) { $search_params{page} = $_; my $next_results = $ils->search(\%search_params); ... } or my $native_result = $ils->native_search(\%native_search_params);
WebService::ILS is an attempt to create a standardised interface for online library services providers.
In addition, native API interface is provided.
Here we will describe constructor parameters and methods common to all service providers. Diversions and native interfaces are documented in corresponding modules.
OverDrive Library API https://developer.overdrive.com/discovery-apis
OverDrive Circulation API https://developer.overdrive.com/circulation-apis
Method calls will die on error. $@ will contain a multi-line string. See error_message() below.
error_message()
Item record is returned by many methods, so we specify it here.
id
isbn
title
subtitle
description
author
publisher
publication_date
language
rating
popularity
subjects
facets
media
formats
images
encryption_key
drm
Not all fields are available for all service providers. Field values are not standardised.
client_id
client_secret
library_id
user_agent
user_agent_params
access_token
access_token_type
These are also read-only attributes
Not all of client/library params are required for all service providers.
As provided to constructor, or auto created. Useful if one wants to change user agent attributes on the fly, eg
$ils->user_agent->timeout(120);
query
page_size
page
sort
Sort options are either an array or a comma separated string of options:
available_date
Sort order can be added after option with ":", eg "publication_date:desc,rating:desc"
items
pages
total
available
copies_available
copies_owned
type
Not all fields are available for all service providers. For example, some will provide "copies_available", making "available" redundant, whereas others will just provide "available".
Simplified version of item_availability()
Provider authentication API is used to get an authorized session.
An example:
my $ils = WebService::ILS::Provider({ client_id => $client_id, client_secret => $client_secret, }); eval { $ils->auth_by_user_id( $user_id, $password ) }; if ($@) { some_error_handling(); return; } $session{ils_access_token} = $ils->access_token; $session{ils_access_token_type} = $ils->access_token_type; ... Somewhere else in your app: my $ils = WebService::ILS::Provider({ client_id => $client_id, client_secret => $client_secret, access_token => $session{ils_access_token}, access_token_type => $session{ils_access_token_type}, }); my $checkouts = $ils->checkouts;
User is redirected to the provider authentication url, and after authenticating at the provider redirected back with some kind of auth token. Requires url to handle return redirect from the provider.
It can be used as an alternative to FB and Google auth.
This is just to give an idea, specifics heavily depend on the provider
Returns provider authentication url to redirect to
Returns auth code url param name
my $ils = WebService::ILS::Provider({ client_id => $client_id, client_secret => $client_secret, }); my $redirect_url = $ils->auth_url("http://myapp.com/ils-auth"); $response->redirect($redirect_url); ... After successful authentication at the provider, provider redirects back to specified app url (http://myapp.com/ils-auth) /ils-auth handler: my $auth_token = $req->param( $ils->auth_token_param_name ) or some_error_handling(), return; local $@; eval { $ils->auth_by_token( $auth_token ) }; if ($@) { some_error_handling(); return; } $session{ils_access_token} = $ils->access_token; $session{ils_access_token_type} = $ils->access_token_type; ... Somewhere else in your app: passing access token to the constructor as above
active
checkout_limit
hold_limit
In addition to Item record fields described above, item records will have:
placed_datetime
queue_position
In addition, total field will be incorported as well.
Returns true in case user does not have a hold on the item. Throws exception in case of any other failure.
checkout_datetime
expires
url
files
Returns true in case user does not have the item checked out. Throws exception in case of any other failure.
All Discovery and Circulation methods (with exception of remove_hold() and return(), where it does not make sense) have native_*() counterparts, eg native_search(), native_item_availability(), native_checkout() etc.
In case of single item methods, native_item_availability(), native_checkout() etc, they take item_id as parameter. Otherwise, it's a hashref of HTTP request params (GET or POST).
Return value is a record as returned by API.
Individual provider subclasses provide additional provider specific native methods.
ERROR_ACCESS_TOKEN
ERROR_NOT_AUTHENTICATED
Example:
my $res = eval { $ils->checkout($id) }; if ($@) { my $msg = $ils->error_message($@); display($msg); log_error($@); }
Federated search
Copyright (C) Catalyst IT NZ Ltd Copyright (C) Bywater Solutions
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Srdjan Janković <srdjan@catalyst.net.nz>
To install WebService::ILS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::ILS
CPAN shell
perl -MCPAN -e shell install WebService::ILS
For more information on module installation, please visit the detailed CPAN module installation guide.