Migration for Existing Partners

Overview

With the launch of this developer portal, we are introducing a new endpoint and authentication methods for developers and end users.  These are the only changes required to use the new endpoint and as you will read below are fairly trivial to implement.  One benefit of migrating to the new endpoint is that you will have reporting on how your application uses the Bookshare API.  To maximize the granularity of reporting, we recommend you review the Reporting  documentation below, which makes recommendations on the order of parameters in your API calls.

Authentication to the API

Legacy applications that use the service.bookshare.org should be migrated to use the api.bookshare.org endpoint. The new endpoint does not use basic auth for authenticating the developer/partner.  Instead, you must append all requests with an application key that you obtain by signing up for a developer account and registering your application.  For each application or device that you wish to connect to the Bookshare API, you must obtain a new application key.  Below is an example of a generally available web service request using an application key:


https://api.bookshare.org/book/searchFTS/title/alchemist?api_key=YOUR_API_KEY

User Authenticated Services

These are services performed and authenticated for a specific end user. With the legacy endpoint, you used a combination of a for parameter with the end user's email address in the URI and passing the end user's password along with the web service user password using basic auth.

With the new endpoint, the end user's email is still passed via the for parameter in the URI.  However, the MD5 of just the end user's 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/for/EMAIL_OF_END_USER/content/250448/version/1?api_key=YOUR_API_KEY

For the privacy of our user data we require that authenticated requests be made via HTTPS.

Search

The search methods in the API have been updated to use our SOLR text search engine instead of SQL based search.  As a result, wildcard operators commonly used in SQL text based search are not applicable.  SOLR text search uses phonetic matching and stemming by default.  This results in a broader set of results.  If you wish to limit the use of phonetic matching or stemming, you must enclose each search term in URL encoded quotes (%22).

Reporting

Partners now can access application specific reporting via the developer portal by going to the My Account section of the portal and selecting the View Report link under each registered application. 

Method level reporting (see example below) is based on the first two keywords in the URI path (e.g /book/browse).  We have updated our documentation to order parameters in a way that provides greater differentiation between method calls.  Unfortunately, you will not be able to differentiate between all method calls, such as between /book/browse/popular and /book/browse/latest, since the first path keywords do not change.  We hope to address this shortcoming in future releases.

Note that reports are updated every 24 hours, so you may not see results right away.  Here are some example reports:

Example developer reports.