Web Services User Stories

Skip to end of metadata
Go to start of metadata

Bookshare Web Service Use Cases

This page lists some of the common use cases to use Bookshare Web Services:

Use Case: Anonymous Book Search & Download

Overview:

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.

Details on Public Domain Search:

  • 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:
    • Title
    • Author
    • Short Synopsis
    • Long Synopsis
    • Book Quality
    • Quality Score
    • Page Numbers
    • ISBN
    • Publisher
    • Copyright date
    • Copyright owner
    • Date added to the Bookshare collection (basically you can get the 'latest' books here)
    • Adult content flag
    • Language(s)
    • Categories
    • 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.
service.bookshare.org/book/search/title/*potter*

<book>
    <list>
        <page>2</page>
        <limit>5</limit>
        <num-pages>10</num-pages>
	<result>
		<id>156244</id>
		<title>The Deathly Hallows Lectures: The Hogwarts Professor Explains the Final Harry Potter Adventure</title>
		<author>John Granger</author>
		<freely-available>0</freely-available>
		<available-to-download>0</available-to-download>
	</result>
	<result>
		<id>151899</id>
		<title>Harry Potter's Bookshelf</title>
		<author>John Granger</author>
		<freely-available>0</freely-available>
		<available-to-download>0</available-to-download>
	</result>
        ...
    </list>
</book>

Details on Public Domain Download:

  • 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).
service.bookshare.org/download/content/1910/version/1

Use Case: (Individual Member) Downloading Copyright Books

Overview:

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. 

Details on Copyright Search & Download:

  • 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.
service.bookshare.org/book/search/title/*potter*/for/user@email.com/

<book>
    <list>
        <page>2</page>
        <limit>5</limit>
        <num-pages>10</num-pages>
	<result>
		<id>156244</id>
		<title>The Deathly Hallows Lectures: The Hogwarts Professor Explains the Final Harry Potter Adventure</title>
		<author>John Granger</author>
		<freely-available>0</freely-available>
		<available-to-download>1</available-to-download>
	</result>
	<result>
		<id>151899</id>
		<title>Harry Potter's Bookshelf</title>
		<author>John Granger</author>
		<freely-available>0</freely-available>
		<available-to-download>1</available-to-download>
	</result>
        ...
    </list>
</book>

Details on Finding the "latest" books added to Bookshare:

  • 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).
    service.bookshare.org/book/search/since/01012000
    
    <bookshare>
      <messages>
        <string>Results 1 - 100 of 36,592</string>
      </messages>
      <book>
        <list>
          <page>1</page>
          <limit>100</limit>
          <num-pages>366</num-pages>
          <result>
            <id>484848</id>
            <title>An 'Attic Philosopher, Volume 2</title>
            <author>Emile Souvestre</author>
          </result>
          ....
        </list>
      </book>
    </bookshare>
    
  • 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.
    service.bookshare.org/book/search/since/01012000/limit/250
    
    <bookshare>
      <messages>
        <string>Results 1 - 250 of 36,592</string>
      </messages>
      <book>
        <list>
          <page>1</page>
          <limit>250</limit>
          <num-pages>147</num-pages>
          <result>
            <id>484848</id>
            <title>An 'Attic Philosopher, Volume 2</title>
            <author>Emile Souvestre</author>
          </result>
          ....
        </list>
      </book>
    </bookshare>
    
  • Fetch subsequent pages as shown below.
    service.bookshare.org/book/search/since/01012000/limit/250/page/2
    
    <bookshare>
      <messages>
        <string>Results 251 - 500 of 36,592</string>
      </messages>
      <book>
        <list>
          <page>2</page>
          <limit>250</limit>
          <num-pages>147</num-pages>
          <result>
            <id>585858</id>
            <title>Abiding Love</title>
            <author>Kate Welsh</author>
          </result>
          ....
        </list>
      </book>
    </bookshare>
    
  • 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.
    service.bookshare.org/book/search/since/12012008/limit/250
    
    <bookshare>
      <messages>
        <string>Results 1 - 10 of 10</string>
      </messages>
      <book>
        <list>
          <page>1</page>
          <limit>250</limit>
          <num-pages>1</num-pages>
          <result>
            <id>585860</id>
            <title>2010: Odyssey Two</title>
            <author>Arthur C. Clarke</author>
          </result>
          ....
        </list>
      </book>
    </bookshare>
    

Use Case: Periodical Fetching and Downloading

Overview:

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.

Periodical List Search

  • 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.
service.bookshare.org/periodical/list

Periodical List Response:
<periodical>
	<list>
		<page>2</page>
		<limit>5</limit>
		<num-pages>10</num-pages>
		<result>
			<id>686868</id>
			<title>AARP_Bulletin</title>
		</result>
		<result>
			<id>787878</id>
			<title>Albany_Times_Union<title>
		</result>
		...
	</list>
</periodical>

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.
    service.bookshare.org/periodical/id/686868
    
    Periodical List Response:
    <periodical>
    	<list>
    		<page>1</page>
    		<limit>100</limit>
    		<num-pages>1</num-pages>
    		<result>
    			<id>686868</id>
    			<edition>12012008</edition>
    			<revision>2</revision>
    			<title>AARP_Bulletin</title>
    		</result>
    	</list>
    </periodical>
    

Periodical Edition Lookup

  • For each Edition in the response above, pull out the Edition Metadata information.
    service.bookshare.org/periodical/id/686868/edition/11012008
    
    Periodical Edition Metadata Response:
    <periodical>
    	<metadata>
    		<content-id>808080</content-id>
    		<brf>1</brf>
    		<daisy>1</daisy>
    		<edition>12012008</edition>
    		<revision>2</revision>
    		<revision-time>0851</revision-time>
    		<category>Magazines</category>
    	</metadata>
    </periodical
    

Periodical Download

  • A Periodical may be downloaded with the Content Id specified in the Periodical Edition Lookup Metadata response retrieved in the previous step.
    service.bookshare.org/download/for/for@mycompany.org/content/808080/version/1
    
    Binary Response:
    

Details on "eligible" periodical downloads:

  • 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.
    service.bookshare.org/periodical/list/for/for@mycompany.org
    

Use Case: Organization Member Download

Overview:

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.
  1. User Type (once for each session)
    DESCRIPTION Get Available Preferences for the given User (IM/OM)
    API service.bookshare.org/user/for/user@foo.com/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)
  2. If IM:
    1. Issue a download request for that IM
      DESCRIPTION Download the title as usual for the IM account\
      API service.bookshare.org/download/for/user@foo.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
  3. If OM:
    1. If Download Password not set:
      1. Set Download Password
        DESCRIPTION Prompt the User for a Download Password and set the Sponsor's Download Password at Bookshare
        API service.bookshare.org/user/for/user@foo.com/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.

    2. Is NIMAC Title?
      1. 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).
      2. If the Member for whom the Title is being downloaded has no IEP certificate return Error Code 82.
    3. Get Member List
      DESCRIPTION Get a list of Members for the Sponsor's Organization
      API service.bookshare.org/user/for/user@foo.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)
      * Name
      * School
      * District


    4. Download a title for one Member.
      DESCRIPTION Download a title for one Member identified by member option
      API service.bookshare.org/download/for/user@foo.com/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 (user@foo.com) downloads the book for Member with ID (1234567890) returned in the "/members/list" response.

    5. Repeat step 3c & 3d for each Member selected.
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.