Integration with OverDrive API (v.2) needed

[Beth Willis]

Evergreen v.3.1
Chrome v.72.0.3626.109, Firefox v.64.0.2

OverDrive Inc. has released an update to the Library Availability API. According to OverDrive’s documentation, the update is intended “to improve availability information and better support the sharing of copies between related accounts (consortia and member libraries [i.e., Advantage Accounts]). In order to support our partners currently using the availability API, we are releasing these changes on a new version of the Library Availability API endpoint (version 2).“

Version 2 of the API needs to be integrated with Evergreen so that copies of a title that have been purchased by member libraries through their OverDrive Advantage accounts are accounted for in the display of available copies. Currently, these copies are not represented in the total number of available copies.

Version 2 solves these problems.

[Beth Willis (willis-a)]

Related to the above bug report, if a title was purchased by a member library through their OverDrive Advantage account, but was not purchased by our consortium (NOBLE, Inc.), the catalog indicates that no copies are available. Note: in some cases the display indicates “status: null of null available” and in others “status: 0 of 0 available”. A screenshot is attached.

[Beth Willis (willis-a)]

Another example related to the bug report. If copies of a title have been purchased both by NOBLE, Inc. and by one or more libraries through their OverDrive Advantage accounts, the copies purchased by the libraries do not display in the catalog. A screenshot is attached. In this case, NOBLE owns a total of 11 copies of Nine Perfect Strangers; 8 purchased by the consortium and 3 through libraries' OverDrive Advantage accounts.

[Martha Driscoll (mjdriscoll)]

OverDrive.pm sets a discovery_base_uri of 'https://api.overdrive.com/v1'. I added an 'availability_base_uri' set to 'https://api.overdrive.com/v2' and changed the functions that lookup holdings and availability to use the new base uri. Several other functions still require the v1 base uri.

Here is my commit:

https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/driscoll/lp1818144_overdrive_api_v2

[Jason Stephenson (jstephenson)]

Martha, thanks for the branch, but the code is incomplete. It is missing a database upgrade script to add the ebook_api.overdrive.availability_base_uri to the config.org_unit_setting_type table.

I'm removing the pullrequest tag and replacing it with needsrepatch.

CW MARS is interested in this as a part of working on bug 1861013.

[Martha Driscoll (mjdriscoll)]

I added an upgrade script and updated seed data.

https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/driscoll/lp1818144_overdrive_api_v2

[Jessica Woolford (jwoolford)]

We tested this patch, and it seemed to work in testing so we applied it to our production system. We discovered that it works for OverDrive Advantage titles that were shared with the consortium, but if titles are not shared, they are still displaying as "null of null" or "0 of 0."

[Martha Driscoll (mjdriscoll)]

Thanks for testing Jessica. I'll take another crack at it. We don't have Advantage titles that are not shared so I did not see this problem, but Overdrive has a testing environment so I'll look at that.

[Martha Driscoll (mjdriscoll)]

It would be helpful if someone with Advantage titles that are not shared with the consortium could post the JSON here. There is a tool in the support-scripts directory to query Overdrive: overdrive-api-checker.pl. the syntax is:

./overdrive-api-checker.pl --account {account ID} --verbose --token {basic token} --endpoint https://api.overdrive.com/v2/collections/{collection token}/products/{titleID}/availability

The account ID and basic token are in library settings. The title ID for the specific title is in the Marc 037 subfield a. The collection token can be found by querying the library collection API:

./overdrive-api-checker.pl --account {account ID} --verbose --token {basic token} --endpoint https://api.overdrive.com/v1/libraries/{account ID}

It would be helpful to see the V1 JSON as well:

./overdrive-api-checker.pl --account {account ID} --verbose --token {basic token} --endpoint https://api.overdrive.com/v1/collections/{collection code}/products/{titleID}/availability

Here is the JSON for a shared Advantage title:

{
    "accounts": [
        {
            "copiesAvailable": 1,
            "copiesOwned": 1,
            "id": 63,
            "shared": true
        },
        {
            "copiesAvailable": 1,
            "copiesOwned": 1,
            "id": -1
        }
    ],
    "availabilityType": "Normal",
    "available": true,
    "copiesAvailable": 2,
    "copiesOwned": 2,

Library 63 owns a copy that is shared and the consortium (id -1) also owns a copy.

[Jeff Davis (jdavis-sitka)]

Here are the JSON responses I got for an Advantage title that isn't shared with the rest of the consortium:

./overdrive-api-checker.pl --account {account ID} --verbose --token "{basic token}" --endpoint https://api.overdrive.com/v2/collections/{Advantage collection token}/products/F2AF3EE4-044B-4A9A-A160-1FBF6F6EE25B/availability
{
  "reserveId": "F2AF3EE4-044B-4A9A-A160-1FBF6F6EE25B",
  "titleId": 9314012,
  "links": {
    "self": {
      "href": "https://api.overdrive.com/v2/collections/{Advantage collection token}/products/F2AF3EE4-044B-4A9A-A160-1FBF6F6EE25B/availability",
      "type": "application/vnd.overdrive.api+json"
    }
  },
  "accounts": [
    {
      "id": 121,
      "shared": false,
      "copiesOwned": 1,
      "copiesAvailable": 1
    }
  ],
  "available": true,
  "availabilityType": "Normal",
  "copiesOwned": 1,
  "copiesAvailable": 1,
  "numberOfHolds": 6
}

./overdrive-api-checker.pl --account {account ID} --verbose --token "{basic token}" --endpoint https://api.overdrive.com/v1/collections/{Advantage collection token}/products/F2AF3EE4-044B-4A9A-A160-1FBF6F6EE25B/availability
{
  "id": "F2AF3EE4-044B-4A9A-A160-1FBF6F6EE25B",
  "crossRefId": 9314012,
  "links": {
    "self": {
      "href": "https://api.overdrive.com/v1/collections/{Advantage collection token}/products/F2AF3EE4-044B-4A9A-A160-1FBF6F6EE25B/availability",
      "type": "application/vnd.overdrive.api+json"
    }
  },
  "collections": [
    {
      "id": "X Public Library",
      "copiesOwned": 1,
      "copiesAvailable": 1,
      "numberOfHolds": 0
    }
  ],
  "available": true,
  "availabilityType": "Normal",
  "copiesOwned": 1,
  "copiesAvailable": 1,
  "numberOfHolds": 6
}

[Martha Driscoll (mjdriscoll)]

I just want to capture something that Jeff said in IRC: when the query was done using the consortia's collection token a TitleNotFoundError was returned. Using the Advantage library's collection token was needed to obtain the availability data.