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