API Reference Guide

Here you'll find a simple reference guide that will help you use OverDrive APIs and understand how they work.

Common terms

• Access Token:  A string that allows access to the OverDrive APIs when passed as part of the 'Authentication' HTTP header.  This is part of the OAuth 2.0 Client Credentials Grant Type.
  
  
• Advantage Accounts:  Products (titles) that have been purchased to supplement a library's digital collection.  These add to whatever titles libraries have access to through their base consortium collection.  You can use 'advantageAccount' hypermedia links from the Library Account API to access Advantage-title-only collections, or complete library collections that include both Advantage and base consortium titles.
  
  
• Authorization Header:  An HTTP header used to send authentication credentials when using HTTP authentication.
  
  
• Availability:  The status of a library title.  Using the Availability API, you can see whether or not a title is available, how many copies a library owns, how many are on hold, and how many are checked out.
  
  
• Base Consortium:  The consortium collection of products (titles) available to a library excluding Advantage titles.
  
  
• Basic Authentication:  HTTP authentication allowing a client to provide their username and password when making a request.  The user name is appended with a colon and attached to the password.  The resulting Base64 encoded string is sent with the HTTP request in the HTTP Authorization header.
  
  
• Client Key:  A value passed as part of the OAuth 2.0 Client Credentials Grant Type that identifies the client requesting access.  Think of it as a complex username that we generate for you.
  
  
• Client Secret:  A value passed as part of the OAuth 2.0 Client Credentials Grant Type that is bound to a specific client key.  Think of it as a complex password that we generate for you.
  
  
• Endpoint:  The entry point for a service.  In the case of the OverDrive APIs, each endpoint is a URL.
  
  
• Forwarded User's IP Address:  The IP address of the end user who is accessing an API through your application.  Please forward this value to us using the HTTP 'X-Forwarded-For' header unless your app runs directly on an end-user's device.
  
  
• HTTP Header:  Key/value pairs passed as part of an HTTP request or response.  Standard header fields are defined as part of the HTTP protocol.
  
  
• Hypermedia Link:  A URL included in an API response which allows you navigate to another related API resource.  These related resources are labeled with a 'rel' identifier.
  
  
• JSON (JavaScript Object Notation):  An open standard for transmitting structured data over the internet.  It is human-readable, and is generally more compact than XML.
  
  
• Library Account:  A library's digital collection of products (titles).  The Library Account API is used to get the information you need to access the other APIs for a given library.
  
  
• Metadata:  Short for 'Product Metadata', this refers to the information we use to describe a particular title or product.
  
  
• OAuth:  An open standard for secure, web-based authorization.  We are using OAuth 2.0.
  
  
• Pagination:  We use this to separate a large set of results into smaller chunks (pages) which can be retrieved using separate requests.  Hypermedia links are used to page (or move) through these results.
  
  
• Product:  An individual title (like an eBook or audiobook).
  
  
• Products Link:  A URL pointing to an endpoint that lists all of the available products in a collection.  This is the base for the Search API.
  
  
• Query Parameter:   A key/value pair passed on the URL as part of a full query string.  These parameters are a standard way to pass values as part of an HTTP GET request.
  
  
• Rel (Relationship):  An identifier used to define the relationship between a hypermedia link and the resource you're currently accessing.  The same 'rel' should always link to the same kind of resource, regardless of where the link is found.  So, 'metadata' will always link to detailed metadata for a specific product based on the context of the link.
  
  
• Retailer Account:  A retailer's digital collection of products (titles).  The Retailer Account API is used to get the information you need to access the other APIs for a given retailer.
  
  
• REST:  A style of Web API that emphasizes defining 'resources' and interacting with them via standard HTTP verbs (GET, PUT, POST, DEL, etc.).
  
  
• Search:  Built on the Products link, our Search API utilizes a URL query string to filter and organize the products (titles) available in a collection.  You can use this to get a response listing titles that match specific criteria.
  
  
• User Agent:  This is a string value passed in the HTTP User-Agent header that identifies the web browser or app accessing an online resource.
  
  
• Web API (Application Programming Interface):  A set of HTTP request messages with a clearly defined response structure.  Ours are designed to access digital media collections for libraries and retailers.
  
  

OverDrive Formats

Each format has a unique identifier which is included in any API response that references title format.  Identifiers can be passed to the Search API to filter results.

Access the Library Account API to see a list of formats available for a specific digital collection. Not all digital collections include every OverDrive format.

Common HTTP Response Codes

Below you'll find a list of the most common HTTP response codes returned by our APIs:

• 200 OK:  This means everything is just fine.
• 400 Bad Request:  The request could not be understood by the server due to malformed syntax (such as a bad query string).
• 401 Unauthorized:  A user token has expired, is invalid, or attempted to access an endpoint to which it does not have access.
• 404 Not Found:  The item requested was not found, or the URL used to make the call was invalid.
• 500 Internal Server Error:  This means something went wrong on our end.  Please send us the response you get so we can figure out what happened.
• 503 Service Unavailable:  We're likely experiencing some temporary down-time.  Please let us know when you experienced the trouble and what request you were making.

How to handle Error Response Codes

When you get certain response codes in the HTTP header, you also get a JSON response that includes details about what happened. That JSON response includes a token that we can use to track down what went wrong.

Here's what an error response looks like

{
    "message":"An unexpected error has occurred.",
    "token":"b31e17ef-608f-442f-92f1-d0c883673f5a"
}

Please submit a support request that includes the entire error response, and we'll get back to you as soon as we can.