This is an old revision of the document!
Connections API features (preliminary)
Proposed implementation principles
3 level integration:
Standard Connections and Reviews implementation in search results, item details pages and at ANY item information throughout catalog (like checked out items, reading history, etc.)
Search results enhancement using ChiliFresh data
Open issues
If and how do we implement looking at other user profiles in Connections?
How do we style widgets? Do we agree on dimensions and styles before?
What do we show to a user if Connections is not accessible (for whatever reason)?
How do we handle errors/conflicts of single-sign on, e.g., user logs on OPAC user account, but for some reason (incorrect identifier, inexistent user, etc.) does not get logged in Connections?
How do we ask users to write reviews on the items they check back in? E-mail them?
How do we handle users that already are ChiliFresh users and will have registered with the particular e-mail addresses?
How do we identify OPAC requests with user_key parameter? Can we set up specific OPAC IP(s)?
User functions
Register
[API/widget/lightbox]
Login
[API/widget/lightbox]
-
Get/edit user information
[API/widget/lightbox]
Gender
City (gets from library's settings, but can edit)
State (gets from library's settings, but can edit)
Country (gets from library's settings, but can edit)
Favorite quote
Birth date + whether to show it on profile
Current read - ISBN/UPC
User picture (3 sizes, JPG, GIF or PNG)
Facebook integration (user ID for opening user's FB page)
Twitter integration (username for opening Twitter profile)
User's news / updates (
API/widget can show new items since last session in each)
[API/widget/lightbox]:
Reviews
Recommendations
Friending invitations
Comments (like other user posts on wall)
Messages (internal messaging)
Replies to user's posts in discussion groups
Book clubs that are about to start
User statistics (includes user's data + average for the same number for all of user's friends)
[API/widget]:
User histories
[API/widget/lightbox]:
Who visited user's profile (last 10 people)
Which profiles user visited (last 10 people)
Which items user last visited (last 10 items)
Get/set user interests -
[API/lightbox]
Bookshelf functions
bookshelfCreate: create new user bookshelf
Creates a new user bookshelf
Parameter | Type (size) | Mandatory |
action | bookshelfCreate | Yes |
account | Integer (10) | Yes |
shelfname | Variable characters(50) | Yes |
default | yes/no | No (default: no) |
public | yes/no | No (default: no) |
session_id | ChiliFresh session - retrieved from userRegister, userLogin or userCreateSession call | Yes |
location | Variable characters (40) | If applicable |
api_key | Variable characters (40) | Yes |
Output
XML output example:
<?xml version="1.0"?>
<response>
<response_code>2100</response_code>
<response_description>Bookshelf created successfully</response_description>
<response_time>Sat, 27 Dec 2014 13:02:20</response_time>
<user_id>64</user_id>
<shelf_id>22773</shelf_id>
<shelf_name>APIshelf</shelf_name>
</response>
Response code
Code | Code description |
2100 | Bookshelf created successfully |
2101 | Empty bookshelf name |
60 | Session invalid, expired or empty |
bookshelfDelete: delete an existing bookshelf of user
Delete an existing bookshelf of user
Parameter | Type (size) | Mandatory |
action | bookshelfDelete | Yes |
account | Integer (10) | Yes |
shelf_id | Integer(10) | Yes |
session_id | ChiliFresh session - retrieved from userRegister, userLogin or userCreateSession call | Yes |
location | Variable characters (40) | If applicable |
api_key | Variable characters (40) | Yes |
Output
XML output example:
<?xml version="1.0"?>
<response>
<response_code>123</response_code>
<response_description>Shelf deleted successfully</response_description>
<response_time>Sat, 27 Dec 2014 13:51:32</response_time>
</response>
Response code
Code | Code description |
2200 | Shelf deleted successfully |
2201 | Cannot delete bookshelf |
60 | Session invalid, expired or empty |
bookshelfChangeSettings: change settings of bookshelf
Changes settings of a bookshelf
Parameter | Type (size) | Mandatory |
action | bookshelfChangeSettings | Yes |
account | Integer (10) | Yes |
shelf_id | Integer (10) | Yes |
default | yes/no | No |
public | yes/no | No |
session_id | ChiliFresh session - retrieved from userRegister, userLogin or userCreateSession call | Yes |
location | Variable characters (40) | If applicable |
api_key | Variable characters (40) | Yes |
Output
XML output example:
<?xml version="1.0"?>
<response>
<response_code>2300</response_code>
<response_description>Settings changed successfully</response_description>
<response_time>Sat, 27 Dec 2014 15:30:23</response_time>
</response>
Response code
Code | Code description |
2300 | Settings changed successfully |
2301 | Cannot change settings to bookshelf |
60 | Session invalid, expired or empty |
bookshelfAddItem: add an item to bookshelf
Add an item - book, CD, DVD, etc. - to an existing bookshelf
Parameter | Type (size) | Mandatory |
action | bookshelfAddItem | Yes |
account | Integer (10) | Yes |
shelf_id | Integer (10) | Yes |
item_id | ISBN, UPC, ISSN, etc. | Yes |
cf_item_id | Integer (10) - item identifier from CF database | No |
item_title | Variable characters (100) - item title | Only if adding unidentified item by item_id |
item_author | Variable characters (100) - item author | Only if adding unidentified item by item_id |
session_id | ChiliFresh session - retrieved from userRegister, userLogin or userCreateSession call | Yes |
location | Variable characters (40) | If applicable |
api_key | Variable characters (40) | Yes |
Output
XML output example:
<?xml version="1.0"?>
<response>
<response_code>2400</response_code>
<response_description>Item added to shelf successfully</response_description>
<response_time>Sat, 27 Dec 2014 15:46:04</response_time>
</response>
Response code
Code | Code description |
2400 | Item added to shelf successfully |
2401 | Cannot identify item |
2402 | Cannot add item to bookshelf |
2403 | Empty item identifier |
60 | Session invalid, expired or empty |
Error code | Error description |
0 | System error |
1 | Invalid (empty) API key |
2 | Invalid API key |
3 | API key request limit reached |
4 | API key deactivated |
5 | Invalid API call |
20 | Empty account ID |
30 | Account does not exists |
40 | Account suspended |
50 | Action not specified |
For all features [API/lightbox]:
Get bookshelves - there can be several created by user
Create / delete bookshelves
Get bookshelf items - get items on particular bookshelf, sort them by title, author
Add item to bookshelf - add items to particular bookshelf. There is “default bookshelf” setting
Remove item from bookshelf
Move item between bookshelves
Create bookshelf widget - create widget and then retrieve code snippet for posting on blog or Facebook page
Import items - import items from files from other services like Goodreads, Shelfari, etc.
Item functions
For all features [API/lightbox]:
Add item manually - if item does not show up in library's or Connections search results, add item manually by adding ISBN/UPC, title, author and cover
Set item as current read - user can set current read to display on profile
Get item information - title, author, ISBN, etc. that we may have
Get item users (users who have item on their bookshelves)
Item tagging - get, add tags for particular item, retrieve items by tags. Tags distinguished between user's own tags and other user tags
Follow/unfollow item - user can follow particular item and see who added item to bookshelf, recommended, reviewed it, etc.
Get followings - get a list of events on followed items
Get suggested items - Connections item recommendations based on particular item, other users having it on their bookshelves, other items other users have on their bookshelves, have reviewed, recommended, etc.
Get items other users visited who checked out particular item - like on Amazon - where you can see what other users bought after buying particular item
Get related users - get users that are similar to particular user based on their bookshelves, other items other users have on their bookshelves, have reviewed, recommended, etc.
Get related communities - get communities that are related as above
Get related book clubs - get book clubs that are related as above
Get related discussion groups - get discussion groups that are related as above
Get related chat rooms - get chat rooms that are related as above
Personal item details - when user started/ended reading, comments, etc. This is private, does not get shared
Novelist data - gets Novelist content for particular item from
API
Friends / users functions
For all features [API/lightbox]:
Get user's friends + links to their profiles
Follow/unfollow other users
Online/offline parameter of user
Get “My followings” - which users/friends the user follows
Get followings - get a list of events on which friend or person user follows has done
Browse library users
View other user profile
Instant messaging with user online [if user online]
Send internal mail message to user
Invite a friend who is not yet on Connections
Shared items - which items on user bookshelves are in common
Item recommendation functions
For all features [API/lightbox]:
List functions
For all features [API/lightbox]:
Get communities list + search
Get book clubs list + search
Get discussion groups list + search
Get chat rooms list + search
Get tags list + search
Get friends + search
Get library's users + search
Specific functions
All features in [lightbox]:
Discussion groups - see all, favorites, join one, create one, etc.
Chat rooms - see all, favorites, join one, create one, etc.
Book clubs - see all, favorites, join one, create one, etc.
Communities - see all, favorites, join one, create one, etc.
Reference desk chat - talk to reference desk librarian
Internal messaging - see all sent/received messages, send a message to user