Page History

Purpose

This document is to help you connect your library's RB Digital RBdigital collection to your Library Simplified circulation manager.

Getting Access

To

...

connect your library's

...

RBdigital account to your Library Simplified circulation manager, you

...

Info

title	Overdrive API Types

Overdrive distinguishes between "Discovery" and "Circulation" APIs.
To quote the glossary:

Discovery APIs: Discovery APIs are designed to allow your users to browse and explore OverDrive digital collections. You can search for titles, check availability, and get details on specific titles.
Circulation APIs: These APIs are designed to allow you to circulate content from an OverDrive digital collection. You can borrow and place holds on titles, see what a specific user has borrowed or placed on hold, and get download links for content that a user has borrowed.

Library Simplified uses the Discovery APIs to keep track of the items in your Overdrive collection, and the Circulation APIs to conduct transactions on behalf of your patrons. Library Simplified needs access to both.

must have two key data elements:

RBdigital's numeric ID for the library
An API access token

Finding the Numeric ID

Assuming the library has registered with RBdigital for service, you can find its RBdigital numeric id by searching the RBdigital API with a non-authenticated request. Let's assume the library's name is "Somewhere County Library". Search the API by copying the following URL into your web browser to submit the request.

http://api.rbdigital.com/v1/suggestive/libraries?q=somewhere

You will receive a response that looks something like the following document. Obviously, this is just an example, with 'St' being a two-letter state abbreviation. If the distinctive portion of the name you search for is really distinctive, you may only receive one result; however, you may also receive multiple "similar" results as shown.

[
{
"url": "somewherest.rbdigital.com/",
"id": "888",
  "category": "ST",
  "value": "somewhere-county-library",
  "label": "Somewhere County Library"
},
{
  "url": "somewheretx.rbdigital.com/",
  "id": "9999",
  "category": "TX",
  "value": "somewhere-public-library",
  "label": "Somewhere Public Library"
}
]

Requesting an Access Token

RBdigital used basic HTTP authentication for securing access to its API. You will need an access token provided by RBdigital staff to facilitate the authentication in API requests. The "basic token" is a UUID value of the form AB71A495-49D1-2C8E-417A-EBB7FB66F51E. The exact letter values may be different, but the form will be the same.

The best method of communication to obtain the token is email. We've provided a basic email template you can use below. The To field address (yoursupport@recordedbooks.com) is correct. For the rest of the message, substitute your library's information for the values shown in angle brackets.

To: yoursupport@recordedbooks.com
From: <personal emailname>@<somewherecounty.com> Subject: RBDigital API Credentials for SimplyE Partner Library

Our library is implementing the SimplyE platform to provide aggregated access to our ebook and audiobook resources. To integrate our RBdigital collection, we need to obtain an access token (UUID). Specific library information is included below.

RBdigital numeric ID: <888>

<Somewhere County Library
123 W. Anywhere Ave.
Somewhere, ST 99999>

Thank you for your assistance.

In case there is any confusion or problems, the street/mailing address will serve to uniquely identify the library.

Once you submit your email, you will receive an automated response with a case number within just a few minutes. Approximately one day later you can expect to receive a second email indicating your request has been escalated to the developer team for assistance. You can expect the response from the developers to take longer, perhaps several days. Because obtaining the access token can take a while, we recommend making the request as early in your implementation process as possible.

Configuring the Circulation Manager

Open a web browser and enter the URL to your Circulation Manager's Admin interface: for example, https://simplye

...

You'll be asked which API (actually which authentication technique) you want access to. Ask for access to all three.

Note

title	Ask for All Three

You will probably only need two of the three, but the approval process is slow, it doesn't cost anything extra to get all three, and you won't have to go back and re-apply if your authentication situation changes.

Info

title	Authentication Types

When the Library Simplified circulation manager makes a call to the Overdrive API, Overdrive needs to verify that the circulation manager is authorized to act on behalf of your library. If the circulation manager is acting on behalf of a specific patron (e.g. creating a loan), Overdrive also needs to know that the circulation manager is authorized to act on behalf of that patron.

Overdrive offers three types of authentication:

Client authentication verifies that the circulation manager is authorized to act on behalf of the library. It's used by scripts that run in the background to maintain an accurate picture of your library's Overdrive collection.
Patron authentication and
Granted authentication

2 and 3 are used when the circulation manager is carrying out the wishes of a specific patron.

In all three cases, the goal is to get an access token. An access token is a string that you can present to the Overdrive API to get it to actually do something. An Overdrive access token is generally good for one hour. Once it expires, you need to get a new one.

Note

title	Apply for Access Early!

It can take a week or more to get approved for API access, so don't put this off!

...

Under "Planned API usage", mention the name of your library and that you are integrating your Overdrive collection into the SimplyE system.

...

Wait for Overdrive to send you an email with production IDs needed to configure your Circulation Manager Overdrive Collection.

Note

title	Sandbox vs Production IDs

When Overdrive gets back to you, they may give you a website ID of 100300 and a library ID of 4425. Those are the IDs for the Overdrive test library. If this happens to you, go back to them and tell them that you need the production IDs to integrate your library into the SimplyE system.

Configuring Circulation Manager

Step 1 Open a web browser and open your circulation manager admin interface. This is you circulation manager URL with https://circulation.libraryname-state.org/admin
Step 2 From In the top menu bar, click click System Configuration to to enter into the the Configuration Manager portion portion of the Admin interface.
Image Modified
Step 3 Select Click the Collections item from the menu on the left and select left menu.
Click Create a new collection
Image Modified
Step 4 Select OverdriveSelect the RBDigital item from the Protocol drop down field.

...

Image Added

Fill Step 5 Fill in the configuration form
- Under Name, enter the collection Name (example: “Overdrive”)
- Under Parent, enter the Parent Account name if applicable
- Under Library ID, enter ID provided by Overdrive
- Under Website ID, enter your circ manager URL
- Under Client Key, enter key provided by Overdrive
- Under Client Secret, enter secret provided by Overdrive
- Under ILS Name, enter the name of your ILS
- Under Add Library, select the library this collection servers from drop down menu.
- Click Submit

Image Removed

More about Overdrive Authentication

Panel

bgColor	#fff
title	Client Authentication

Client authentication is pretty simple. Overdrive issues you a set of credentials: a client key and a client secret. At any time, you can show those credentials to Overdrive to get an access token. Although this is the simplest way to get an an access token, the token is not authorized to act on behalf of a specific patron. You can look at the collection but you can't borrow books.

Panel

bgColor	#fff
title	Patron Authentication

Patron authentication is the simplest way of getting an access token to act on behalf of a patron. It can only be used when your library does authentication by username and password (or equivalent pieces of information, such as barcode and PIN).

To get an access token with patron authentication, you provide your client key and client secret (as with client authentication), but you also provide the patron's username and password.

Overdrive checks the patron's username and password with your ILS. If the ILS says the username and password are valid, you get an access token.

This access token can act on behalf of the patron whose username it was associated with. You can borrow books, place holds, etc.

As with other access tokens, this token is only good for an hour.

Panel

bgColor	#fff
title	Granted Authentication

Granted authentication is a more complex way of getting an access token to act on behalf of a patron.

When you set up granted authentication with Overdrive, you'll be asked to set up a "redirect URI". (You can change your redirect URI here.) Your redirect URI should point to the oauth_calback controller of your circulation manager, e.g.:

https://my-circulation-manager.com/oauth_callback?provider=Overdrive

When a patron tries to check out a book through Overdrive, Library Simplified circulation manager will tell them to visit a URL based on this template:

https://oauth.overdrive.com/auth?client_id={ID}&redirect_uri={URLredirectedTo}&scope=accountId:{ID}&response_type=code&state={optionalStateParameter}

Overdrive will redirect the patron to... some URL somewhere. I's unclear yet if it's a URL on your ILS or one managed by Overdrive. Either way, the patron will be asked to log in. Once they log in they will be asked to authorize Library Simplified to act on their behalf. Once they allow this, Overdrive will send them to your redirect URI:

https://my-circulation-manager.com/oauth_callback?provider=Overdrive&state={optionalStateParameter}&code={authorizationCode}

The circulation manager can then use the {authorizationCode} to get an access token to act on behalf of the patron.

- enter a descriptive phrase for the collection: for example, Somewhere County Library - RBdigital
- Under Basic Token, enter token provided by RBdigital (as shown above)
- Under Library ID, enter the RBdigital library ID you found for your library above
Image Added
Add your library record to the configuration:
- Select your library from the Add Library drop down list
- (Optional, to assist in estimating hold/due periods) Enter a value in days into the Audiobook Loan Duration field
- (Optional, as above) Enter a value in days into the Ebook Loan Duration field
- Click the Add Library button to attach your library record to the collection
Image Added
Click the Submit button to save the RBdigital collection configuration

Page tree

Versions Compared

Old Version 3

New Version Current

Key

Purpose

Getting Access

Finding the Numeric ID

Requesting an Access Token

Configuring the Circulation Manager

Configuring Circulation Manager

More about Overdrive Authentication

Related articles