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.
Item record is returned by many methods, so we specify it here.
idisbntitlesubtitledescriptionauthorpublisherpublication_datelanguagerating => user ratings metricspopularity => checkout metricssubjects => subject categories (tags)facets => a hashref of facet => [values]media => book, e-book, video, audio etcformats => an arrayref of available formatsimages => a hashref of size => urlencryption_key => for decryption purposesdrm => subject to drmNot all fields are available for all service providers. Field values are not standardised.
client_id => client (vendor) identifierclient_secret => secret key (password)library_id => sometimes service providers provide access to different "libraries"user_agent => LWP::UserAgent or a derivative; usually not needed, one is created for you.user_agent_params => LWP::UserAgent constructor params so you don't need to create user agent yourselfaccess_token => as returned from the provider authentication systemaccess_token_type => as returned from the provider authentication systemThese 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 => query (search) stringpage_size => number of items per results pagepage => wanted page numbersort => resultset sort option (see below)Sort options are either an array or a comma separated string of options:
publication_date => date title was publishedavailable_date => date title became available for usersrating => number of items per results pageSort order can be added after option with ":", eg "publication_date:desc,rating:desc"
items => an array of item recordspage_size => number of items per results pagepage => results page numberpages => total number of pagestotal => total number of items found by the searchidavailable => booleancopies_available => number of copies availablecopies_owned => number of copies ownedtype => availability type, provider dependentNot 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
An example:
my $ils = WebService::ILS::Provider({
client_id => $client_id,
client_secret => $client_secret,
});
my $redirect_url = $ils->auth_url("https://myapp.com/ils-auth");
$response->redirect($redirect_url);
...
After successful authentication at the provider, provider redirects
back to specified app url (https://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
idactive => booleancopies_available => number of copies availablecheckout_limit => number of checkouts allowedhold_limit => number of holds allowedtotal => number of items on holditems => list of individual itemsIn addition to Item record fields described above, item records will have:
placed_datetime => hold timestamp, with or without timezonequeue_position => user's position in the waiting queue, if availableIn addition, total field will be incorporated as well.
Returns true in case user does not have a hold on the item. Throws exception in case of any other failure.
total => number of items on holditems => list of individual itemsIn addition to Item record fields described above, item records will have:
checkout_datetime => checkout timestamp, with or without timezoneexpires => date (time) checkout expiresurl => download/stream urlfiles => an arrayref of downloadable file details title, url, sizeIn addition, total field will be incorporated as well.
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_TOKENERROR_NOT_AUTHENTICATEDExample:
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>