Install Now
WebService::ILS - Standardised library discovery/circulation services
Contents
Attributes
user_agent
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);
Circulation Methods
patron()Returnspatronrecord:
"id"
"active" => boolean
"copies_available" => number of copies available
"checkout_limit" => number of checkouts allowed
"hold_limit" => number of holds allowed
holds()Returnsholdsrecord:
"total" => number of items on hold
"items" => list of individual items
In addition to Item record fields described above, item records will have:
"placed_datetime" => hold timestamp, with or without timezone
"queue_position" => user's position in the waiting queue, if available
place_hold($item_id)Returnsholdsitemrecord(asdescribedabove)
In addition, "total" field will be incorported as well.
remove_hold($item_id)Returnstruetoindicatesuccess
Returns true in case user does not have a hold on the item. Throws exception in case of any other
failure.
checkouts()Returnscheckoutrecord:
"total" => number of items on hold
"items" => list of individual items
In addition to Item record fields described above, item records will have:
"checkout_datetime" => checkout timestamp, with or without timezone
"expires" => date (time) checkout expires
"url" => download/stream url
"files" => an arrayref of downloadable file details title, url, size
checkout($item_id)Returnscheckoutitemrecord(asdescribedabove)
In addition, "total" field will be incorported as well.
return($item_id)Returnstruetoindicatesuccess
Returns true in case user does not have the item checked out. Throws exception in case of any other
failure.
Constructor
new(%params_hashor$params_hashref)Client(vendor)relatedconstructorparams,givenbyserviceprovider:
"client_id" => client (vendor) identifier
"client_secret" => secret key (password)
"library_id" => sometimes service providers provide access to different "libraries"
Generalconstructorparams:
"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 yourself
"access_token" => as returned from the provider authentication system
"access_token_type" => as returned from the provider authentication system
These are also read-only attributes
Not all of client/library params are required for all service providers.
Description
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.
SupportedserviceprovidersWebService::ILS::OverDrive::Library
OverDrive Library API <https://developer.overdrive.com/discovery-apis>
WebService::ILS::OverDrive::Patron
OverDrive Circulation API <https://developer.overdrive.com/circulation-apis>
Discovery Methods
search($params_hashref)Inputparams:
"query" => query (search) string
"page_size" => number of items per results page
"page" => wanted page number
"sort" => resultset sort option (see below)
Sort options are either an array or a comma separated string of options:
"publication_date" => date title was published
"available_date" => date title became available for users
"rating" => number of items per results page
Sort order can be added after option with ":", eg "publication_date:desc,rating:desc"
Returnssearchresultsrecord:
"items" => an array of item records
"page_size" => number of items per results page
"page" => results page number
"pages" => total number of pages
"total" => total number of items found by the search
item_metadata($item_id)Returnsitemrecorditem_availability($item_id)Returnsitemavailabilityrecord:
"id"
"available" => boolean
"copies_available" => number of copies available
"copies_owned" => number of copies owned
"type" => availability type, provider dependant
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".
is_item_available($item_id)Returnsboolean
Simplified version of item_availability()Individual User Authentication And Methods
user_id/password
Provider authentication API is used to get an authorized session.
auth_by_user_id($user_id,$password)
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;
Authenticationattheprovider
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
auth_url($redirect_back_uri)
Returns provider authentication url to redirect to
auth_token_param_name()
Returns auth code url param name
auth_by_token($provider_token)
An example:
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
Interface
Errorhandling
Method calls will die on error. $@ will contain a multi-line string. See "error_message()" below.
Itemrecord
Item record is returned by many methods, so we specify it here.
"id"
"isbn"
"title"
"subtitle"
"description"
"author"
"publisher"
"publication_date"
"language"
"rating" => user ratings metrics
"popularity" => checkout metrics
"subjects" => subject categories (tags)
"facets" => a hashref of facet => [values]
"media" => book, e-book, video, audio etc
"formats" => an arrayref of available formats
"images" => a hashref of size => url
"encryption_key" => for decryption purposes
"drm" => subject to drm
Not all fields are available for all service providers. Field values are not standardised.
License
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.
Name
WebService::ILS - Standardised library discovery/circulation services
Native Methods
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.
Synopsis
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);
Todo
Federated search
Utility Methods
Errorconstants
"ERROR_ACCESS_TOKEN"
"ERROR_NOT_AUTHENTICATED"
error_message($exception_string)Returnserrormessageprobablysuitablefordisplayingtotheuser
Example:
my $res = eval { $ils->checkout($id) };
if ($@) {
my $msg = $ils->error_message($@);
display($msg);
log_error($@);
}
is_access_token_error($exception_string)Returnstrueiftheerrorisaccesstokenrelatedis_not_authenticated_error($exception_string)Returnstrueiftheerroris"Notauthenticated"
PNG Icons
