WebService::ILS(3pm)

💖 WebService::ILS 💖

okay bestie, sit DOWN, because we're talking about WebService::ILS — it's the standardised library discovery/circulation services situation, and it lives in the User Contributed Perl Documentation section of your manual. this page is the group chat for every service provider subclass, so let's get into it 🦋

---

✨ SYNOPSIS ✨

like, here's the vibe:

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, alternatively, the other route:

my $native_result = $ils->native_search(\%native_search_params);

---

🌸 DESCRIPTION 🌸

so WebService::ILS is literally an attempt to create a standardised interface for online library services providers. that's the whole mission statement, no cap.

plus, a native API interface is provided too. two for one, we love to see it 💅

and here's the tea: on this page we're describing constructor parameters and methods common to all service providers. the diversions and native interfaces? those get documented in their corresponding modules. iykyk.

👑 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, bestie. $@ will contain a multi-line string. see "error_message()" below for how to cope with that emotionally.

🍓 Item record

the Item record gets returned by many methods, so we're specifying it right here, once, so nobody has to ask twice:

• 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

heads up: not all fields are available for all service providers. and field values are not standardised. it's giving chaos but we move 🌈

---

🌟 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 different "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, jsyk ✨

and ngl: not all of client/library params are required for all service providers.

---

🦋 ATTRIBUTES 🦋

user_agent

as provided to constructor, or auto created. super 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" — periodt.

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

returns item record 🎀

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.

it's the simplified version of item_availability() — main character energy, less drama.

---

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

🔐 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. this requires a url to handle the return redirect from the provider.

it can be used as an alternative to FB and Google auth. iconic.

this is just to give an idea — specifics heavily depend on the provider, so don't come for me 🌸

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

---

💜 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 the 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. dramatic but fair 😤

checkouts ()

returns checkout record:

• total — number of items on hold
• items — list of individual items

in addition to the 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)

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. it's giving "i have a twin" 💅

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. yes, the subclasses are the ones with extra lore ✨

---

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

is_not_authenticated_error ($exception_string)

returns true if the error is "Not authenticated".

---

🙈 TODO 🙈

• Federated search

(that's it. that's the whole list. we're manifesting it fr fr 🫶)

---

📜 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 JankoviX <srdjan@catalyst.net.nz>

---

and that's the whole page bestie!! this was WebService::ILS(3pm) from perl v5.36.0, dated 2022-11-29 — go forth and search, hold, checkout and return, you absolute icon 👑🌸💅