API V1.0 User Preferences

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:

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
  }
}}