Bookshare API V1.0 Getting Started
Notice: The Bookshare API V1 will be sunset on June 30, 2024 and will no longer be available. Partners will need to migrate to API V2 to continue accessing the Bookshare collection after that date. Learn about API V2.
Bookshare partners play a critical role. They help make ebooks available in accessible formats to people who cannot read standard print all around the world. By providing access to Bookshare’s huge collection of accessible titles and integrating key Bookshare app features, partners make it easier for people with disabilities to read what they want, how they want.
Bookshare is currently on its V2 API, which uses more industry standard conventions (OAuth2 authorization, and RESTful constraints) for increased security and easier integration. It also supports more features, including Reading Lists and Assign & Read, as well as user roles that allow Membership and Collection management.
We are currently making improvements to our V2 API and evaluating our API partner agreement. Existing partners can continue to access Bookshare’s API to provide access to Bookshare content. New partners will be evaluated and granted access after our improvements are complete. We thank you for your interest and patience. If you have any questions, please contact us at partner-support@bookshare.org.
User Authenticated Services
These are services performed and authenticated for a specific end user. These include search, downloading of content, user preference modification, etc. These services must be authenticated both by your application key and the end user’s Bookshare Account. If the specific end user account is an Organization Membership, it can also download on behalf of their Organization member. In the cases of search, the specified user is used to determine which titles are available to download given that specific user’s restrictions and permissions.
For user authenticated services, the user’s username will be passed in via the for parameter in the endpoint path. The password should be derived as (Java syntax): md5sum(userPassword), where userPassword is the password of the user on whose behalf the service is being requested. The password is passed via a custom HTTP header named X-password. Here is an example request using the Unix curl command:
curl -k -H "X-password:MD5_OF_ENDUSER_PASSWORD" \
https://api.bookshare.org/download/content/250448/version/1/for/EMAIL_OF_END_USER?api_key=YOUR_API_KEYFor the privacy of our user data we require that authenticated requests be made via HTTPS.
To test user authenticated services, please read Bookshare Test Data for Partners.
Generally Available Services
These services need be authenticated only by your application key. These include browsing and searching both book and newspaper/magazine content.
When to use User Authenticated vs. Generally Available Services
The unauthenticated calls are meant for users who either don’t yet have a Bookshare account and want to see what’s in our library or for users who want to see what a particular app/device can do before they feel comfortable entering their login info.
In the case where a user has entered their login credentials, user authenticated calls allow them to search (../book/search , ../book/latest, ../book/popular, etc.) for titles and the app/device can indicate (or only choose to show) which books are available to download. And then the user can get more information on a particular book from that search result set (via the ../book/id call) and choose to successfully download the book.
Individual (IM) Members vs. Organizational (OM) Members vs. Sponsors
Bookshare supports two different member types: Individual Members (IM) and Organizational Members (OM), plus another role called Organizational Sponsors. Sponsors are associated with an Organization and act as a facilitator for the OM’s. An example of a Sponsor would be an educator who might download on behalf of a student and/or may set the student up with their own student login (e.g. a username and password). IM’s can download any book that is available to them based on access rights granted by the publisher or country’s copyright rules, while OM’s with their own login can download only the books that have been assigned to them by sponsors. Sponsor accounts are also subject to the same access rights as IM’s, but Sponsors are required to indicate the OM for whom they are downloading the title.
Since the process flow for a Sponsor downloading a book for an OM is different than for an IM user, we recommend that after requesting an end user’s Bookshare login credentials, you determine whether they are an IM, and OM, or Organizational Sponsor by requesting from the API their user type. If they are a Sponsor, you will need to make additional API calls to:
- Obtain the list of Org Members for which they are authorized to download on behalf of.
- Specify the member-id for whom they are executing the download request.
You can learn more about Organizational Sponsors and Members here.