Notice: The Bookshare API V1 will be sunset on June 30, 2024 and will no longer be available. Partners will need to migrate to API V2 to continue accessing the Bookshare collection after that date. Learn about API V2.

URI	Details	Response
api.bookshare.org/user/preferences/list/for/Text	User Preference List	User Preference List Response
api.bookshare.org/user/preference/Number/set/Text/for/Text	User Preference Modification	User Preference List Response

User Preference List

• Description: Get the User Preference Fields that are alterable for the given user.
• Format: api.bookshare.org/user/preferences/list/for/Text, where the for parameter specifies the email address/username of the end user for whom the download is being requested for.  In addition the MD5 hash of the end user password must be passed in the request via a “X-password” HTTP header.
• Authentication: User Authenticated
• Response: User Preference List Response
• Examples:
  • api.bookshare.org/user/preferences/list/for/user@foo.com

User Preference Fields

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

User Preference Modification

• Description: Change the value of one of the user’s preferences.  It returns the user’s updated preferences being listed so that you can redisplay in your UI.
• Format: api.bookshare.org/user/preference/Number/set/Text/for/Text, where the for parameter specifies the email address/username of the end user for whom the download is being requested for.  In addition the MD5 hash of the end user password must be passed in the request via a “X-password” HTTP header.
• Authentication: User Authenticated
• Response: User Preference List Response
• Examples:
  • api.bookshare.org/user/preference/01/set/true/for/user@foo.com
  • api.bookshare.org/user/preference/01/set/false/for/user@foo.com
  • api.bookshare.org/user/preference/11/set/mypassword/for/user@foo.com 
• Errors:
  • Error 75 – The Preference Value being set for (aaa) is read-only. aaa will be replaced by the name of the read only preference. Occurs when a user attempts to set a value for a read-only preference.

User Preference List Response

Container: user

Fields

Field	Type	Description	Occurrence
downloads-remaining	Number	Indicates the number of downloads remaining for this User	1

Container: user/list/result

Additional Fields

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

XML Example:

<bookshare>
  <version>3.2.8</version>
  <messages>
    <string>User account information for user@foo.com</string>
  </messages>
  <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>FALSE</value>
        <editable>1</editable>
      </result>
      <result>
        <id>02</id>
        <name>User Type</name>
        <value>1</value>
        <editable>0</editable>
      </result>
    </list>
  </user>
</bookshare>

JSON Example:

{"bookshare": {
  "version": "3.5.1",
  "messages": [
    "User account information for user@foo.com"
  ],
  "user": {
    "result": [
      {
        "id": "01",
        "name": "Adult Content filtering",
        "value": "FALSE",
        "editable": 1
      },
      {
        "id": "02",
        "name": "User Type",
        "value": "1",
        "editable": 0
      }
    ],
    "downloadsRemaining": 100
  }
}}