| WebService::ILS(3pm) | User Contributed Perl Documentation | WebService::ILS(3pm) |
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.
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.
Not all fields are available for all service providers. Field values are not standardised.
Client (vendor) related constructor params, given by service provider:
General constructor params:
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);
Input params:
Sort options are either an array or a comma separated string of options:
Sort order can be added after option with ":", eg "publication_date:desc,rating:desc"
Returns search results record:
Returns item record
Returns item availability record:
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".
Returns boolean
Simplified version of item_availability()
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;
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
Returns patron record:
Returns holds record:
In addition to Item record fields described above, item records will have:
Returns holds item record (as described above)
In addition, "total" field will be incorported as well.
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.
Returns checkout record:
In addition to Item record fields described above, item records will have:
Returns checkout item record (as described above)
In addition, "total" field will be incorported as well.
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.
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.
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($@);
}
Returns true if the error is access token related
Returns true if the error is "Not authenticated"
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 JankoviX <srdjan@catalyst.net.nz>
| 2022-11-29 | perl v5.36.0 |