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>

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"

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

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

Not all of client/library params are required for all service providers.

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

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_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

Simplified version of item_availability()

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

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

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

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"