- Bookshare Web Service Use Cases
- Use Case: Anonymous Book Search & Download
- Use Case: (Individual Member) Downloading Copyright Books
- Details on Copyright Search & Download:
- Details on Finding the "latest" books added to Bookshare:
- Use Case: Periodical Fetching and Downloading
- Details on "eligible" periodical downloads:
- Use Case: Organization Member Download
This page lists some of the common use cases to use Bookshare Web Services:
Anyone can freely choose to search for and download a book that is outside of copyright (e.g. any public domain, creative commons, etc.), select it for download and have it automatically open and start reading.
- Books can be searched by a Web Service account without specifying a Bookshare User Account, also referred to as an Anonymous Book Search.
- LL: We need to remove the requirement for ANY account at all (topic under discussion)
- Book search should allow for single or multi-field search parameters as the end client prefers
- Single field search will perform a full text search on the book, but author and title are weighted more heavily in the relevancy score
- Multi-field search will allow searching by any or all of the following fields, "title", "author", "copyright date (year)", "date added", "full text"
- Search results will be returned with only non-copyright books in the result set and sorted by relevancy score (the score will be returned to allow you to choose how much to display
- Search results will include the book formats available for download (which will also give you information on if images are contained - DAISY with images) along with all of the book metadata that is displayed currently on the www.bookshare.org website Book Details page, which includes:
- Short Synopsis
- Long Synopsis
- Book Quality
- Quality Score
- Page Numbers
- Copyright date
- Copyright owner
- Date added to the Bookshare collection (basically you can get the 'latest' books here)
- Adult content flag
- Regional availability
- In Anonymous Book Search, titles will not be filtered.
- Freely Available titles indicated by freely-available, identifies whether this title can be downloaded or not without User Authentication.
- Anonymous Book Downloads are supported only for titles that belong to Public Domain, also referred to as Freely Available.
- Freely Available titles indicated by freely-available in search results.
- The following sample URL downloads book "Tom Sawyer Abroad, by Mark Twain" that is freely available without specifying the User Account (/for).
Only authenticated (logged in/registered) Bookshare members can download copyright materials. The user will have to authenticate and then perform a title search - by Title, Author, and/or ISBN - and return a result set that indicates if each title is "eligible to download" by the authenticated user. "Eligible" in this case evaluates regional restrictions, NIMAC access, membership and subscription status. End users want to retrieve books in all accessible formats (DAISY, BRF and ultimately DAISY with images). And end users want to easily find the "latest" books added to the collection.
- Books can be searched for a specific Bookshare User Account where the results will be restricted based on Region restrictions.
- There may still however be certain books in the results that is not available for download for this User because their Subscription may have been expired, or they may need to sign Membership Agreement etc.
- Search results will include an indicator available-to-download that specifies a true indicator whether the user would be able to download that title or not.
- In order to Fetch newly Published Books from Bookshare, one would need to fetch ALL Book information once at that point in time. Lets say that point in time is (12012008).
- To optimize the response handling, the maximum limit allowed may be used as documented in Web Service response Paging and Limit. In this example, it reduces the number of pages that will need to retrieved from 366 to 147.
- Fetch subsequent pages as shown below.
- Once the initial repository is fetched, every night incremental updates can be retrieved. For instance in this case, lets attempt to retrieve updated Books since last attempt on 12012008.
Users want to search for and have daily automated updates of any periodicals for which they are eligible to download. This Use Case lists all necessary steps involved in browsing/fetching Periodicals, their Editions/Revisions and eventually downloading them.
- The first step involved is fetching a list of Periodicals available.
- The list of periodicals available to this user, if user authenticated; all periodicals otherwise.
- This fetch is required once to get a list of most recent Periodicals supported at Bookshare.
- The IDs from this response can be stored to get more details about each Periodical via Periodical Edition Search.
- For each Periodical Id that you have fetched for the User via the Periodical List response, make the following call to retrieve the Periodical Editions available.
- For each Edition in the response above, pull out the Edition Metadata information.
- A Periodical may be downloaded with the Content Id specified in the Periodical Edition Lookup Metadata response retrieved in the previous step.
- Alternately Periodical List can also be fetched more catered to the User Account (as specified in the /for clause).
- This list will include Periodicals available to the User Account based on Country and NewsLine State.
The use cases above for authenticated search and download assumes and individual member downloading for themselves. In order to allow for a download "on behalf of" another member (in this case a teacher downloading for a student), an additional scenario is required to be supported whereby a teacher searches for and selects a book for download and has to indicate the student or students that he/she is downloading the book "on behalf of" in order to have the appropriate DRM assigning the individual (student) to the title (this is also called "fingerprinting" in packaging).
- An Organization Member Book or Periodical Edition download needs to identify the Organization Members for whom the Book/Periodical Edition is being downloaded for.
- And then issue a Download for the Organization Member one at a time.
- The following steps identifies the necessary steps for an Organization Download.
- Steps Overview: Assuming that the vendor application will maintain the state, there will be at most 3 user actions required for an OM download.
- (Once per session) Sponsor authenticates with their Bookshare password.
- (Once) Enter Sponsor's Download Password if missing.
- (Each new OM Download request) Choose member(s) to download for.
- User Type (once for each session)
DESCRIPTION Get Available Preferences for the given User (IM/OM) API firstname.lastname@example.org/preferences/list PASSWORD md5sum(WEB_SERVICE_ACCOUNT.password + USER_ACCOUNT.password) END_USER_ACTION May be Required the first time, depending on how the state is maintained by the vendor app RESPONSE The response here includes the following information:
* Adult Content Filtering (true/false)
* User Type (1=IM; 2=OM)
* Download Password (only if the user is an OM)
- If IM:
- Issue a download request for that IM
DESCRIPTION Download the title as usual for the IM account\ API email@example.com/content/1892124/version/1 PASSWORD md5sum(WEB_SERVICE_ACCOUNT.password + USER_ACCOUNT.password) END_USER_ACTION N/A if password is remembered by vendor app RESPONSE Binary Download
- Issue a download request for that IM
- If OM:
- If Download Password not set:
- Set Download Password
DESCRIPTION Prompt the User for a Download Password and set the Sponsor's Download Password at Bookshare API firstname.lastname@example.org/preference/11/set/foohbahpassword PASSWORD md5sum(WEB_SERVICE_ACCOUNT.password + USER_ACCOUNT.password) END_USER_ACTION Required (enter a new Sponsor Download Password)
Note: Preference "11" represents the Download Password ID sent in step 1.
- Set Download Password
- Is NIMAC Title?
- If Organization is not authorized to download NIMAC titles, return Error Code 41 (with detailed message indicating the Organization is unauthorized to download NIMAC titles).
- If the Member for whom the Title is being downloaded has no IEP certificate return Error Code 82.
- Get Member List
DESCRIPTION Get a list of Members for the Sponsor's Organization API email@example.com/members/list PASSWORD md5sum(WEB_SERVICE_ACCOUNT.password + USER_ACCOUNT.password) END_USER_ACTION Required - Choose Member(s) to download for. RESPONSE The response includes the following details for each member:
* ID (Obfuscated ID)
- Download a title for one Member.
DESCRIPTION Download a title for one Member identified by member option API firstname.lastname@example.org/member/1234567890/content/1892124/version/0 PASSWORD md5sum(WEB_SERVICE_ACCOUNT.password + USER_ACCOUNT.password) END_USER_ACTION N/A if password is remembered by vendor app RESPONSE Binary Download
Note: The sponsor (email@example.com) downloads the book for Member with ID (1234567890) returned in the "/members/list" response.
- Repeat step 3c & 3d for each Member selected.
- If Download Password not set: