Bookshare API V1.0 Getting Started
To use our web service (API) you first need to get an application key. You should obtain a different application key for each application or device accessing our web service, so that you and Bookshare can properly track usage per application. To get an application key, email firstname.lastname@example.org with details of the application you are developing.
The application key needs to be included in all requests to our web service by including it as the api_key parameter to our endpoint. For example:
There are two sets of 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_KEY
For 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 exeuting the download request.
You can learn more about Organizational Sponsors and Members here.