View Source

h1. Bookshare Web Service

*\*The most recent documentation of the web service API calls is now available at* *[Mashery|http://developer.bookshare.org/docs/read/api_overview/Request_and_Result_Formats]**.*

{toc}

*Bookshare Web Service Additional Links*
{children}

h2. Overview

The Bookshare Web Service (BWS) allows third party tool developers to deliver much of the functionality of the Bookshare platform to end users. There are two sets of services:

h2. User Authenticated Services

These are services performed and authenticated for a specific end user. These include downloading of content, user preference modification, etc. These services must be authenticated both by your Web Service Account 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.

h2. Generally Available Services

These services need be authenticated only by your Web Service Account. These include browsing and searching both book and newspaper/magazine content.

h1. Getting Started

To use the service, the following process should be followed:

# Register Web Service Account:
## Sign up as an over 18 individual at [http://www.bookshare.org/signUpAdult].
## Fax the completed and signed [Web Service Agreement|^Terms and Conditions for Bookshare-080308.doc], and [NDA|^NDA_Bookshare_2009-04-22.doc] to 650 475 1066, attn Fanja. Alternately, email support@bookshare.org with a scan of your completed forms.
## Contact support@bookshare.org and laral@benetech.org to request authorization of your account to use the web service.
# Build and test your tool.
# If you wish to offer [#User Authenticated Services], you should submit an evaluation version of your tool (software, hardware or webapp) and source code to Bookshare for a security audit. This may take up to one month. Once approved, your Web Service Account will be authorized to perform user authenticated services on behalf of any Bookshare user who provides their authentication details to your tool. Please contact Lara Long, laral@benetech.org with any questions.

h1. Application Programming Interface

h2. Authentication

The BWS uses HTTP Basic Authentication. The authentication for the Web Service Account must be provided with every request; otherwise the default usage message will be returned. The username is always the Web Service Account username.

h3. Password

h4. User Authenticated

If the request is for a [bookshare:User Authenticated Service|#User Authenticated Services], then the password should be derived as (Java syntax): md5sum(wsaPassword + userPassword), where _wsaPassword_ is the password of the Web Service Account, and _userPassword_ is the password of the user on whose behalf the service is being requested. The user's username will be passed in via the *for* parameter.

Until your tool has been approved by us to serve the general user community, the only user accounts that will work are test accounts specifically set up for you to develop against are ones we will provide for you upon receipt of signed NDA for testing purposes. 


h4. Generally Available

If the request is for a [bookshare:Generally Available Service|#Generally Available Services], then the password should be derived as: md5sum(wsaPassword), where _wsaPassword_ is the password of the Web Service Account.

h2. RESTful API

The BWS uses a RESTful API. URIs are meaningful and for the most part static. They are easy to share. Parameters are specified within the URI's path, rather than tacked on as a list via ? and &.

h2. Result Format

Results can be returned either in JSON or XML format. XML is default. To vary the format, append the *format* parameter to the request URI.

The encoding of the XML and JSON responses will be UTF-8.

|| Parameter || Value || Description ||
| format | xml | XML formatted output |
| format | json | JSON formatted output |

All examples in this document use XML result sets for clarity; the JSON variants have identical data hierarchies and field naming.

h3. Example

* service.bookshare.org/book/isbn/0-262-19502-X/format/json

h2. Paging and Limit

Paging and limit can be controlled by appending the *page* and *limit* parameters to any request which results in a [#Book List Response] or [#Periodical List Response]. A default page of 1 (first) and limit of 100 are applied if these parameters are not specified. The maximum limit is 250 results; any specified limit over this will be rounded down to 250. Negative pages and limits will be ignored and defaults will be used.

|| Parameter || Value || Description ||
| limit | [#Number]\\ | How many results to show in a [bookshare:List Response|#List Responses]\\ |
| page | [#Number]\\ | Which page of results to show |

h3. Examples

* service.bookshare.org/book/isbn/0-262-19502-X/page/10
* service.bookshare.org/book/isbn/0-262-19502-X/limit/10
* service.bookshare.org/book/isbn/0-262-19502-X/page/10/limit/50/
* service.bookshare.org/book/isbn/0-262-19502-X/page/10/limit/50/format/json

h2. Throttling

The service is throttled to 3 requests a second from a given tool. If this isn't sufficient, special arrangements can be made. Excessive downloading by an end user may result in suspension or termination of service.

h2. Errors

Errors will be returned as a number so that your application built around the BWS can take appropriate action. There is exactly one error code per error condition. Error codes will never be changed or reused.

h1. Requests

h2. Definitions

* _Content_ \- Generic name for Book or Periodical.
* _Book_ \- A Book with a Title, Author and ISBN.
* _Periodical_ \- A newspaper or magazine with a Title and many Editions.
* _Edition_ \- An edition of a Periodical with a Title, Date and Revision.
* _Revision_ \- Periodical Editions are often updated during the day. Each has a separate revision number.

h2. Request Specifications

h3. Book Requests

{table-plus:width=800px}

















|| URI || Details || Response ||
| service.bookshare.org/book/isbn/[#Text] | [#ISBN Lookup] | [#Book Metadata Response] |
| service.bookshare.org/book/id/[#Number] | [#Book Id Lookup] | [#Book Metadata Response] |
| service.bookshare.org/book/search/[#Text] | [#Title/Author Search] | [#Book List Response] |
| service.bookshare.org/book/search/title/[#Text] | [#Title Search] | [#Book List Response] |
| service.bookshare.org/book/search/author/[#Text] | [#Author Search] | [#Book List Response] |
| service.bookshare.org/book/search/since/[#Date] | [#Date Added Search] | [#Book List Response] |
| service.bookshare.org/reference/category/list | [#Category List] | [#Category List Response] |
| service.bookshare.org/book/search/[#Text]/category/[#Text] | [#Title/Author Search restricted to Category] | [#Book List Response] |
{table-plus}

h3. Newspaper / Magazine Requests

{table-plus:width=800px}

















|| URI || Details || Response ||
| service.bookshare.org/periodical/id/[#Number] | [#Periodical Edition Search] | [#Periodical List Response] |
| service.bookshare.org/periodical/id/[#Number]/edition/[#Date]/revision/[#Number] | [#Periodical Edition Lookup] | [#Edition Metadata Response] |
| service.bookshare.org/periodical/list | [#Periodical List Search] | [#Periodical List Response] |
{table-plus}

h3. Downloading

{table-plus:width=800px}

















|| URI || Details || Response ||
| service.bookshare.org/download/for/[#Text]/content/[#Number]/version/[#Number] | [#Download Request] | [#Binary Download] |
{table-plus}

h3. User Preferences

{table-plus:width=800px}

















|| URI || Details || Response ||
| service.bookshare.org/user/for/[#Text]/preferences/list | [#User Preference Search] | [#User Preference List Response] |
| service.bookshare.org/user/for[#Text]/preference/[#Number]/set/[#Text] | [#User Preference Modification] | [#User Preference List Response] |
{table-plus}

h2. Request Details

h3. ISBN Lookup

* Description: Look up a specific book by ISBN. Wildcard searches are not permitted. Either 13 or 10 digit ISBNs are accepted. Dashes are optional.
* Format: service.bookshare.org/book/isbn/[#Text]
* Authentication: [#Generally Available]
* Response: [#Book Metadata Response]
* Examples:
** service.bookshare.org/book/isbn/0-262-19502-X/format/json
** service.bookshare.org/book/isbn/026219502X
* Errors:
** [#Error 0] \- Book not found

h3. Book Id Lookup

* Description: Look up a specific book by Bookshare Id. The id is part of the [#Book List Response]
* Format: service.bookshare.org/book/id/[#Number]
* Authentication: [#Generally Available]
* Response: [#Book Metadata Response]
* Examples:
** service.bookshare.org/book/id/12242/format/json
** service.bookshare.org/book/id/12242
* Errors:
** [#Error 0] \- Book not found

h3. Title/Author Search

* Description: Search for books based on the supplied text matching author or title.
* Format: service.bookshare.org/book/search/[#Text]
* Authentication: [#Generally Available] OR [#User Authenticated]
* Response: [#Book List Response]
* Examples:
** service.bookshare.org/book/search/*King
** service.bookshare.org/book/search/*Dark\*
** service.bookshare.org/book/search/Ste*%20Ki*/limit/50
** service.bookshare.org/book/search/Steven%20King/page/2/format/json
* Errors:
** [#Error 10] \- Invalid search character

h3. Title Search

* Description: Search for books based on the supplied text matching the title.
* Format: service.bookshare.org/book/search/title/[#Text]
* Authentication: [#Generally Available] OR [#User Authenticated]
* Response: [#Book List Response]
* Examples:
** service.bookshare.org/book/search/title/*Dark\*
** service.bookshare.org/book/search/title/*Dark%20Half
* Errors:
** [#Error 10] \- Invalid search character

h3. Author Search

* Description: Search for books based on the supplied text matching the author.
* Format: service.bookshare.org/book/search/author/[#Text]
* Authentication: [#Generally Available] OR [#User Authenticated]
* Response: [#Book List Response]
* Examples:
** service.bookshare.org/book/search/author/Steven\*
** service.bookshare.org/book/search/author/*King
** service.bookshare.org/book/search/author/*ven%20King\*
* Errors:
** [#Error 10] \- Invalid search character

h3. Date Added Search

* Description: Search for books that have been added to Bookshare on or since the given date.
* Format: service.bookshare.org/book/search/since/[#Date]
* Authentication: [#Generally Available] OR [#User Authenticated]
* Response: [#Book List Response]
* Examples:
** service.bookshare.org/book/search/since/02062008
** service.bookshare.org/book/search/since/01012000
* Errors:
** [#Error 20] \- Invalid date

h3. Category List

* Description: Get a list of available book categories
* Format: service.bookshare.org/reference/category/list
* Authentication: [#Generally Available] OR \[#User Authenticated\]
* Response: [#Category List Response]
* Examples:
** service.bookshare.org/reference/category/list

h3. Title/Author Search restricted to Category

* Description: Search for books based on the supplied text matching author or title within given category.
* Format: service.bookshare.org/book/search/[#Text]/category/[#Text]
* Authentication: [#Generally Available] OR [#User Authenticated]
* Response: [#Book List Response]
* Examples:
** service.bookshare.org/book/search/*bear*/category/Sports
** service.bookshare.org/book/search/*bear*/category/Animals
* Errors:
** [#Error 83] \- Invalid/Incorrect Category

h3. Periodical Edition Search

* Description: Look up the available editions, including revision numbers, of a given periodical that are in the Bookshare repository.
* Format: service.bookshare.org/periodical/id/[#Number]
* Authentication: [#Generally Available] OR [#User Authenticated]
* Response: [#Periodical List Response]
* Examples:
** service.bookshare.org/periodical/id/14
** service.bookshare.org/periodical/id/19
* Errors:
** [#Error 30] \- Periodical not found

h3. Periodical Edition Lookup

* Description: Look up metadata about a given revision of a given edition of a specific periodical in the Bookshare repository. Revision is optional; if not specified, the default (latest) revision will be provided.
* Format: service.bookshare.org/periodical/id/[#Number]/edition/[#Date]/revision/[#Number]
* Authentication: [#Generally Available] OR [#User Authenticated]
* Response: [#Edition Metadata Response]
* Examples:
** service.bookshare.org/periodical/id/14/edition/02202008/revision/3/
** service.bookshare.org/periodical/id/19/edition/12192008/revision/1/
** service.bookshare.org/periodical/id/19/edition/12192008/
* Errors:
** [#Error 30] \- Periodical not found
** [#Error 31] \- Periodical edition not found
** [#Error 32] \- Periodical revision not found

h3. Periodical List Search

* Description: Get the list of periodicals available to this user, if user authenticated; all periodicals otherwise.
* Format: service.bookshare.org/periodical/list
* Authentication: [#Generally Available] OR [#User Authenticated]
* Response: [#Periodical List Response]
* Examples:
** service.bookshare.org/periodical/list

h3. Download Request

* Description: Download the periodical edition or book based on the content id in the [#Edition Metadata Response] or [#Book Metadata Response], respectively. The user who the download request is being made for is specified. Available versions are BRF (0) or DAISY (1) (depending on indication of availability in the response).
* Format: service.bookshare.org/download/for/[#Text]/content/[#Number]/version/[#Number]
* Authentication: [#Generally Available] only if metadata response indicates it is *freely-available* OR [#User Authenticated]
* Response: [#Binary Download]
* Examples:
** service.bookshare.org/download/for/joe@hotmail.com/content/1892124/version/0
** service.bookshare.org/download/for/user@foo.com/content/1892124/version/1
** service.bookshare.org/download/content/1892124/version/1 (For a Freely-Available Content)
* Errors:
** [#Error 40] \- Content not available
** [#Error 41] \- Content not available to user
** [#Error 42] \- Content not available in requested format
** [#Error 60] \- The Web Service account does not have permission to download the content

h3. User Preference Search

* Description: Get the [#User Preference Fields] that are alterable for the given user. The user whose preferences are being displayed is specified.
* Format: service.bookshare.org/user/for/[#Text]/preferences/list
* Authentication: [#User Authenticated]
* Response: [#User Preference List Response]
* Examples:
** service.bookshare.org/user/for/user@foo.com/preferences/list
* Errors:
** [#Error 75] \- User Preference is read-only. If user attempts to set a value for a read-only preference.

h4. User Preference Fields
{table-plus:width=800px}

















|| Id || Field Description || Occurrence || Editable || Additional Notes ||
| 01 | Adult Content Filtering | 1 | Yes | Always available in the results |
| 02 | User Type | 1 | No | 1=IM; 2=OM |
| 11 | Sponsor Download Password | 0/1 | Yes | Available only to Organization Membership Accounts |
{table-plus}

h3. User Preference Modification

* Description: Change the value of one of the user's preferences. Results in the user's updated preferences being listed so that you can redisplay in your UI. The user whose preferences are being modified is specified.
* Format: service.bookshare.org/user/for/[#Text]/preference/[#Number]/set/[#Text]
* Authentication: [#User Authenticated]
* Response: [#User Preference List Response]
* Examples:
** service.bookshare.org/user/for/user@foo.com/preference/01/set/true
** service.bookshare.org/user/for/user@foo.com/preference/01/set/false
** service.bookshare.org/user/for/sponsor@myorg.com/preference/11/set/mypassword

h3. Organization Member List

* Description: List members available in the Organization identified by the User (Sponsor) Account.
* Format: service.bookshare.org/user/for/Text/*members/list*
* Authentication: [#User Authenticated]
* Response: [#Organization Member List Response]
* Examples:
** service.bookshare.org/user/for/user@foo.com/*members/list*
* Errors:
** [#Error 14] \- No Members available for the Sponsors Organization.
** [#Error 61] \- Unauthorized request. The User is not a valid Sponsor for an Organization.

h3. Organization Download Request

* Description: Download the periodical edition or book based on the content id in the Edition Metadata Response or Book Metadata Response, respectively. The Sponsor of an Organization is specified in the *for* clause. And the Organization Member for whom the download is being made for is specified in the *member* clause. Available versions are BRF (0) or DAISY (1) (depending on indication of availability in the response). Download for a Member should include the Obfuscated Member ID returned in Member List Response.

* Format: service.bookshare.org/download/for/Text/*member/Text*/content/Number/version/Number
* Authentication: [#Generally Available] only if metadata response indicates it is *freely-available* OR [#User Authenticated]
* Response: Binary Download
* Examples:
** service.bookshare.org/download/for/joe@hotmail.com/*member/1234567890*/content/1892124/version/0
** service.bookshare.org/download/for/user@foo.com/*member/987654321*/content/1892124/version/1
* Errors:
** [#Error 13] \- Member ID specified does not exist.
** [#Error 61] \- Unauthorized request. The User is not associated with an Organization.
** [#Error 80] \- Download password not set. If the member does not have a download password defined yet.
** [#Error 82] \- The Member for whom a NIMAC title is being downloaded requires to have IEP certificate. This can be set at Bookshare.org site by the Sponsor.

h4. Additional Information on Organization Member Download of NIMAC Titles

* Organizations attempting to download NIMAC titles must have the following criteria met before their Sponsors can download NIMAC titles. Currently there is no way to work around these errors via Web Service.
* The Sponsors need to log into their Bookshare.org Sponsor accounts and work with Support if they are not authorized to download NIMAC titles.
** The Organization should be approved by a Bookshare Admin that their Sponsor can download NIMAC Books.
** An Organization Member must have IEP Certificate set before the Sponsor can download a NIMAC title for them. The Sponsor can set this for their Members in their Roster at Bookshare.org.

h1. Responses

h2. HTTP Response

h3. HTTP Success Response Codes

* HTTP/1.1 200 OK

h3. HTTP Failure Response Codes

* HTTP/1.1 401 Unauthorized: (Requires user authentication)
* HTTP/1.1 403 Forbidden: (Invalid Login Attempt)
* HTTP/1.1 404 Not Found: (Requested Resource not found)

h3. HTTP Response Headers


h4. Binary Download Response

* Content-Length: Download size in bytes
* Content-Type:
** application/zip (Default ZIP download)
** application/bks2 (BKS2 download format if user-account had set this option under their User Preferences in *www.bookshare.org*)

h4. All other Response

* Content-Type:
** text/xml; charset=UTF-8 (For XML response)
** text/json; charset=UTF-8 (For JSON response)

*Note:* The Content-Size HTTP Header in binary response is now deprecated and will be removed in future Bookshare Service release. Use *Content-Length* instead.

h2. Bookshare Response

Each valid web service request processed will provide a response that will be wrapped in "bookshare" envelope. Along with actual response payload, it also contains the following two information:
# Status Code (0/1: optional) \-> Different from HTTP Response codes.
# Messages (0/n: optional)
# version (1)

h3. Status Code

The Status Code indicates the recognized error as documented in: [#Error Codes]







h4. Example
{code}
<status-code>10</status-code>
{code}

h3. Messages

The Messages indicates the default description of the error. You can render this to your end users if you want.

h4. Example
{code}
<messages>
<string>Invalid Search Character</string>
</messages>
{code}

h3. Complete Examples

h4. 1. Valid Search. (Made status-code as optional)
{code}
(HTTP/1.1 200 OK)
<bookshare>
<book>
<metadata>
<content-id>1000</content-id>
......
</metadata>
</book>
</bookshare>
{code}

h4. 2. Search requested with an invalid search character.
{code}
(HTTP/1.1 200 OK)
<bookshare>
<status-code>0</status-code>
<messages>
<string>Invalid Search Character</string>
</messages>
</bookshare>
{code}

h2. Metadata Responses

These responses provide metadata about the given revision or edition, including the *content id* which is necessary for download.

h3. Common Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| content-id | [#Number] | Id that can be used in [#Download Request] | 1 |
| daisy | [#Number] | If 0, a DAISY download is not available. If 1, a DAISY download is available. | 0/1 |
| brf | [#Number] | If 0, a BRF download is not available. If 1, a BRF download is available. | 0/1 |
{table-plus}

h3. Book Metadata Response

Container: book/metadata

h4. Additional Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| isbn-10 | [#Text] | The 10 digit ISBN, if known | 0/1 |
| isbn-13 | [#Text] | The 13 digit ISBN, if known | 0/1 |
| author | [#Text] | The, or one of the, author(s) of the book | 1/N |
| title | [#Text] | The title of the book | 1 |
| publish-date | [#Date] | The date published in bookshare | 1 |
| publisher | [#Text] | The publisher of the book, if known | 0/1 |
| copyright | [#Date] | The date copyrighted, if known | 0/1 |
| language | [#Text] | The, or one of the, language(s) that the book is in | 0/N |
| brief-synopsis | [#Text] | Brief Synopsis about this Periodical Edition | 0/1 |
| complete-synopsis | [#Text] | Complete Synopsis about this Periodical Edition | 0/1 |
| category | [#Text] | The category this Edition belongs to | 0/N |
| bookshare-id | [#Text] | The Bookshare ID | 1 |
| freely-available | [#Number] | If 0, it is not Freely Available. If 1, it is Freely Available. | 1 |
| available-to-download | [#Number] | If 0, it is not available for download (may be Subscription/Membership related). If 1, it is. | 1 |
{table-plus}

h4. Example

{code}
<book>
<metadata>
<content-id>12345</content-id>
<daisy>1</daisy>
<brf>1</brf>
<isbn-10>12-345-6789X</isbn-10>
<isbn-13>12-345-6789X-123</isbn-13>
<author>Steven King</author>
<author>John Grisham</author>
<author>Martin Amis</author>

<title>The Trial of the Dark Spy</title>
<publish-date>02062008</publish-date>
<publisher>Harper Collins</publisher>
<copyright>1996</copyright>
<language>en</language>
<brief-synopsis>Brief synopsis about this Book. Length=512.</brief-synopsis>
<complete-synopsis>Complete synopsis about this Book. Length=4096.</complete-synopsis>
<category>Mystery</category>
<category>History</category>
<bookshare-id>Bookshare</bookshare-id>
<freely-available>0</freely-available>
</metadata>
</book>
{code}

h3. Edition Metadata Response

Container: periodical/metadata

h4. Additional Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| edition | [#Date] | The edition date | 1 |
| revision | [#Number] | Revision of the edition, to be used in [#Periodical Edition Lookup] | 1 |
| revision-time | [#Number] | Time in PST, 24H format; time that revision was received by Bookshare | 1 |
| category | [#Text] | The category this Edition belongs to | 0/N |
{table-plus}

h4. Example
{code}
<periodical>
<metadata>
<content-id>12346</content-id>
<daisy>1</daisy>
<brf>1</brf>
<edition>12052008</edition>
<revision>4</revision>
<revision-time>1213</revision-time>
<category>Mystery</category>
<category>History</category>
</metadata>
</periodical>
{code}

h2. List Responses

Lists resulting from a search.

h3. Common fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| page | [#Number] | Which page of results this represents | 1 |
| limit | [#Number] | The limit used when running the search | 1 |
| num-pages | [#Number] | The number of pages of results at this value of limit | 1 |
| result | Container | The book/list (or) periodical/list Container | 0/N |
{table-plus}

h3. Book List Response

Container: book/list/result

h4. Additional Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| id | [#Number] | Book id, to be used in [#Book Id Lookup] | 1 |
| title | [#Text] | Title of the book | 1 |
| author | [#Text] | The author(s) of the book | 1/N |
| download-format | [#Text] | Format of download file | 1/N |
| images | [#Number] | If 1, indicates the book has images. 0 indicates it does not. | 1 |
| freely-available | [#Number] | If 1, indicates the Book is Freely Available. 0 indicates it is not. | 1 |
{table-plus}

h4. Example

{code}
<book>
<list>
<page>2</page>
<limit>5</limit>
<num-pages>10</num-pages>
<result>
<id>12378</id>
<title>The Princess Bride</title>
<author>Martin Amis</author>
<author>Mary Lamp</author>
<download-format>Daisy</download-format>
<download-format>BRF</download-format>
<images>1</images>
<freely-available>1</freely-available>
</result>
<result>
<id>12345</id>
<title>The Princess and the Warrior</title>
<author>John Grisham</author>
<download-format>Daisy</download-format>
<download-format>BRF</download-format>
<images>0</images>
<freely-available>0</freely-available>
</result>
<result>
<id>12358</id>
<title>The Princess Diaries</title>
<author>Steven King</author>
<download-format>Daisy</download-format>
<download-format>BRF</download-format>
<images>0</images>
<freely-available>0</freely-available>
</result>
...
</list>
</book>
{code}

h3. Category List Response

Container: category/list/result

h4. Additional Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| name | [#Text] | Category name | 1 |
{table-plus}

h4. Example

{code}
<book>
<list>
<page>1</page>
<limit>100</limit>
<num-pages>1</num-pages>
<result>
<name>Animals</name>
</result>
<result>
<name>Art and Architecture</name>
</result>
<result>
<name>Biographies and Memoirs</name>
</result>
...
</list>
</book>
{code}


h3. Periodical List Response

Container: periodical/list/result

h4. Additional Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| id | [#Number] | Periodical id, to be used in [#Periodical Edition Lookup] | 1 |
| edition | [#Date] | Periodical edition date, to be used in [#Periodical Edition Lookup]. Not included in results from [#Periodical List Search] | 0/1 |
| revision | [#Number] | Revision of the edition, to be used in [#Periodical Edition Lookup]. Not included in results from [#Periodical List Search] | 0/1 |
| title | [#Text] | Title of the periodical | 1 |
{table-plus}

h4. Example

{code}
<periodical>
<list>
<page>2</page>
<limit>5</limit>
<num-pages>10</num-pages>
<result>
<id>12379</id>
<edition>02122008</edition>
<revision>2</revision>
<title>The New York Times</title>
</result>
<result>
<id>12399</id>
<edition>02162008</edition>
<revision>1</revision>
<title>Newsweek</title>
</result>
...
</list>
</periodical>
{code}

h3. User Preference List Response

Container: user

h4. Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| downloads-remaining | [#Number] | Indicates the number of downloads remaining for this User | 1 |
{table-plus}

Container: user/list/result

h4. Additional Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| id | [#Number] | Preference id, to be used in [#User Preference Modification] | 1 |
| name | [#Text] | User preference text to be displayed to the user | 1 |
| value | [#Text] | Current text of the preference | 1 |
| editable | [#Text] | Field editable or not | 1 |
{table-plus}

h4. Example

{code}
<user>
<downloads-remaining>100</downloads-remaining>
<list>
<page>1</page>
<limit>10</limit>
<num-pages>1</num-pages>
<result>
<id>01</id>
<name>Adult Content Filtering</name>
<value>true</value>
<editable>true</editable>
</result>
<result>
<id>02</id>
<name>User Type</name>
<value>2</value>
<editable>false</editable>
</result>
<result>
<id>11</id>
<name>Sponsor Download Password</name>
<value>foobah</value>
<editable>true</editable>
</result>
</list>
</user>
{code}

h3. Organization Member List Response

* The Member ID returned in this response is an obfuscated string that is valid for a certain period of time.
* To perform an action on behalf of a Organization Member, first issue a /member/list and invoke the subsequent step with the Member ID returned in this response to guarantee its validity.
* Caching of Member IDs from this response is not supported.

Container: user

h4. Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurrence ||
| downloads-remaining | [#Number] | Indicates the number of downloads remaining for this User | 1 |
{table-plus}

Container: user/list/result

h4. Additional Fields

{table-plus:width=800px}

















|| Field || Type || Description || Occurence ||
| member-id | [#Text] | Obfuscated User ID | 1 |
| first-name | [#Text] | First Name for the member | 1 |
| last-name | [#Text] | Last Name for the member | 1 |
{table-plus}

h4. Example

* Example:
{code:xml}
<bookshare>
<version>3.1.26</version>
<user>
<downloads-remaining>100</downloads-remaining>
<list>
<page>1</page>
<limit>10</limit>
<num-pages>1</num-pages>
<member>
<member-id>12729908312277e61ef7734273efdd8b85ed9592f1536</member-id>
<first-name>First1</first-name>
<last-name>Last</last-name>
</member>
<member>
<member-id>12729908312273bec4f033592d24c21943a5c5a44d5eb</member-id>
<first-name>First2</first-name>
<last-name>Last</last-name>
</member>
<member>
<member-id>127299083122881878fc887304f199ae6ede548c84fd1</member-id>
<first-name>First3</first-name>
<last-name>Last</last-name>
</member>
</list>
</user>
</bookshare>
{code}

h2. Binary Download

* An encrypted zip containing either a BRF or DAISY package. The zip is encrypted with the user's password, using standard PBE.

h3. PBE Resources

** Windows XP
** Mac OSX
** Linux unzip
** [http://www.jasypt.org/cli.html]

h1. Parameter and Field Types

h2. Number

A positive integer, without commas.

h3. Examples

* 23
* 250
* 2353335

h2. Text

Text. If supplied in a parameter, generally this specifies a search. [#Wildcards] are permitted in certain requests, and should be denoted by the * character. See [#Allowed Punctuation].

h3. Examples

* King\*
* Steven%20King
* The%20Dark%20Half
* \*Dark%20Hal\*

h2. Allowed Punctuation

(Applies only to parameters). The following escape codes must be used in place of the specified characters. Punctuation not in this table will be ignored. (\- and @ may be included directly without escaping them in applicable contexts.)

|| Character || Description || Escape Code ||
| | Space | %20 |
| | Space | \\ |
| " | Quote | " |
| ' | Apostrophe | ' |
| , | Comma | , |
| . | Period | . |
| \- | Dash | None needed |
| @ | Email at | None needed |

h3. Wildcards

|| Character || Description ||
| \* | Non-greedy, matches one or more characters |

h2. Date

Dates should be specified as MMDDYYYY. No punctuation is permitted. Shortening of months, days or years is not permitted.

h3. Examples

* 02121990
* 03252005
* 03012008

h1. Error Codes

h2. Error 0

Book Not Found

h2. Error 10

Invalid Search Character

h2. Error 11

Maximum page number possible is max-possible-page-number

h2. Error 12

Id cannot be used with the Search operation

h2. Error 13

Invalid Member Id specified


h2. Error 14

No Members available for the Sponsors Organization

h2. Error 20

Invalid Date

h2. Error 30

Periodical Not Found

h2. Error 31

Periodical Edition Not Found

h2. Error 32

Periodical Revision Not Found

h2. Error 40

Content Not available

h2. Error 41

Content Not available to User

h2. Error 42

Content not available in requested format

h2. Error 43

Content not found for the given Content Id

h2. Error 44

User Account has not signed the user agreement. Please contact customer support.


h2. Error 50

Invalid/Incomplete request
This error indicates that there are certain invalid parameter values specified in the URL and the detailed message indicates cause of this failure.
For example:
/book/id/abcd \-> _Id must be a valid Number_

h2. Error 51

Invalid Output format
Only xml and json output formats are supported. Any other output format requested will return this error code.

h2. Error 60

Unauthorized access
The User Account does not have enough permissions to perform this action

h2. Error 61

Unauthorized request.
The User is not a valid Sponsor for an Organization

h2. Error 70

PREFERENCE FIELD INVALID
Preference field is invalid. User does not have this option for preference.

h2. Error 71

PREFERENCE ACTION INVALID
The action for the preference is invalid.

h2. Error 72

PREFERENCE ACTION VALUE INVALID
The value for this action is invalid.

h2. Error 73

PREFERENCE ACTION FORMAT INVALID
The format of the request is invalid. The fields may not be in the right order, or incomplete.

h2. Error 74

PREFERENCES TYPE INVALID
The User Action preference request is invalid


h2. Error 75

The Preference Value being set for (USER_TYPE) is read-only


h2. Error 80

Organization Sponsor has no Download password set

h2. Error 81

Download password cannot match user password

h2. Error 82

The Member for whom the title is being downloaded for needs IEP


h2. Error 83

An invalid category was passed in as part of a search. Please use one of the categories listed in the call to service.bookshare.org/reference/category/list

h2. Error 401

Insufficient Privileges
The User does not have privileges to perform the requested operation.

h2. Error 403

Invalid Login attempt
Invalid Credentials Specified.

h2. Error 404

Page Not Found
This error is received if a URL is not recognized.

h2. Error 500

Internal Server Error
Unexpected error encountered while processing the request.