NAME

WebService::ILS - Standardised library discovery/circulation services

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);

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.

Supported service providers

WebService::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

INTERFACE

Error handling

Method calls will die on error. $@ will contain a multi-line string. See error_message() below.

Item record

Item record is returned by many methods, so we specify it here.

id

title

subtitle

subtitle

author

publisher

rating => user ratings metrics

popularity => checkout metrics

subjects => subject categories (tags, facets...)

media => book, e-book, video, audio etc

formats => an arrayref of available formats

Not all fields are available for all service providers. Field values are not standardised.

CONSTRUCTOR

new (%params_hash or $params_hashref)

Client (vendor) related constructor params, given by service provider:

client_id => client (vendor) identifier

client_secret => secret key (password)

library_id => sometimes service providers provide access to differnt "libraries"

General constructor params:

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.

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);

DISCOVERY METHODS

search ($params_hashref)

Input params:

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"

Returns search results record:

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_availability ($item_id)

Returns item availability record:

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)

Returns boolean

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;
   ...
   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;

Authentication at the provider

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;
...
Somewhere else in your app:
passing access token to the constructor as above

CIRCULATION METHODS

patron ()

Returns patron record:

id

active => boolean

copies_available => number of copies available

checkout_limit => number of checkouts allowed

hold_limit => number of holds allowed

holds ()

Returns holds record:

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)

Returns holds item record (as described above)

In addition, total field will be incorported as well.

remove_hold ($item_id)

Returns true to indicate success

Returns true in case user does not have a hold on the item. Throws exception in case of any other failure.

checkouts ()

Returns checkout record:

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

checkout ($item_id)

Returns checkout item record (as described above)

In addition, total field will be incorported as well.

return ($item_id)

Returns true to indicate success

Returns true in case user does not have the item checked out. Throws exception in case of any other failure.

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.

UTILITY METHODS

Error constants

ERROR_ACCESS_TOKEN

ERROR_NOT_AUTHENTICATED

error_message ($exception_string)

Returns error message probably suitable for displaying to the user

Example:

my $res = eval { $ils->checkout($id) }; 
if ($@) {
    my $msg = $ils->error_message($@);
    display($msg);
    log_error($@);
}

is_access_token_error ($exception_string)

Returns true if the error is access token related

TODO

Federated search

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.

AUTHOR

Srdjan Janković <srdjan@catalyst.net.nz>

cpanm WebService::ILS

perl -MCPAN -e shell
install WebService::ILS