API V1.0 User Preferences

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