Difference between revisions of "Common Recommender REST API"
Zeno Gantner (talk | contribs) (→Add New User to Server: clarify) |
Zeno Gantner (talk | contribs) (→Add New User to Server: "to Server" - removed, kind of redundant) |
||
Line 14: | Line 14: | ||
==Working with Users== | ==Working with Users== | ||
− | ====Add New User | + | ====Add New User==== |
;<tt>POST /users</tt> | ;<tt>POST /users</tt> | ||
:Adds a new user to the server. If a user ID is specified in the request body, and currently unused, the user is assigned the ID. If an existing user possesses the ID, the request fails. | :Adds a new user to the server. If a user ID is specified in the request body, and currently unused, the user is assigned the ID. If an existing user possesses the ID, the request fails. |
Revision as of 12:17, 2 December 2011
The MyMediaLite and LensKit projects are seeking to use a common REST API for recommender web applications. Specific implementations are encouraged to support the following core interface, but may extend the API as necessary.
The API is based upon three basic entities:
- Users (referenced by a unique "uid")
- Items (referenced by a unique "iid")
- Events (referenced by a unique "eid")
User, item, and event IDs are strings, but implementations will most likely specify a valid ID format.
An additional type of ID, a revision ID ("rid"), is used to identify any change to a user, item, or event. When one of these entities is either created or updated, the server will return a revision ID in its response. When a client wishes to make changes to a user, item, or event, it must provide the ID of the entity's most recent revision. If this ID is not valid, the client's request will fail.
Each user and item is associated with a set of events. An event is created whenever a user takes some meaningful action involving an item, such as a rating or purchase. This event is then associated with both the user and the item. The specific event types that are supported will vary between different implementations.
Contents
- 1 Working with Users
- 2 Working with Items
- 3 Working with Events
- 4 Miscellaneous
Working with Users
Add New User
- POST /users
- Adds a new user to the server. If a user ID is specified in the request body, and currently unused, the user is assigned the ID. If an existing user possesses the ID, the request fails.
- If no ID is specified, one is is generated for the user by the server and returned in the response.
- The request will also return a new revision ID for use by a future update request.
Add New or Update Existing User
- PUT /users/[uid]
- If the specified ID is unused, a new user is created and assigned this ID.
- If an existing user possesses the ID, the request must provide the user's most recent revision ID in order to update their data.
- The request will return a new revision ID for use by a future update request.
Retrieve User Metadata
- GET /users/[uid]
- Retrieves user data from the server. This includes user attributes, but does not include the user's history of events.
Remove User from Server
- DELETE /users/[uid]
- Deletes the specified user from the server. Precise behavior will vary between implementations.
Access User Statistics
- GET /users/[uid]/statistics
- Retrieves common statistics regarding the specified user. Implementations are free to specify their own fields.
Retrieve User Rating Predictions
Basic HTTP Calls
- GET /users/[uid]/predictions
- Retrieves user rating predictions for all possible items.
Query Parameters
- item
- The ID of an item for which a rating prediction is to be retrieved. Multiple IDs can be specified simultaneously. If no IDs are specified, the server will return predictions for all possible items.
- ex: GET /users/predictions?item=42&item=70 Retrieves user rating predictions for items 42 and 70.
- useStoredRatings
- Enables the server to return a user rating rather than a prediction if one has been provided for an item.
- ex: GET /users/predictions?usedStoredRatings=true Allows the server to retrieve user ratings in place of predictions when they are available.
Retrieve User Item Recommendations
Basic HTTP Calls
- GET /users/[uid]/recommendations
- Retrieves the complete recommendation set for the specified user. If possible, items are returned in ranked order.
Query Parameters
- count
- The maximum number of recommendations to be returned. If this maximum cannot be reached, the server returns as many recommendations as possible.
- ex: GET /users/[uid]/recommendations?count=10 Retrieves a maximum of 10 recommended items.
Access User History
The supported event types will vary between implementation. Each of these event types may also support a unique set of query parameters.
Basic HTTP Calls
- GET /users/[uid]/events
- Retrieves all events associated with the specified user.
- GET /users/[uid]/events/purchases
- Retrieve all events of a specific type (In this case, purchases) associated with the specified user.
- GET /users/[uid]/currentRatings
- Retrieves a simple vector containing the most recent rating of all items currently rated by the user.
- Note that this will return the same set of events as GET /users/[uid]/events/ratings?history=current&null=false, but in a simple vector form.
Query Parameters
- item
- Required for all Event Types
- The ID of an item with which all returned events are associated. If no ID is specified, the server will consider all possible items.
- ex: GET /users/[uid]/events/purchases?item=42&item=70 Retrieves all user purchase events associated with items 42 and 70.
- history
- Required for all Event Types
- The time period during which all returned events occurred.
- ex: GET /users/[uid]/events?history=1m Retrieves all events associated with the user that have occurred within the past month.
- null
- Required Specifically for the Rating Event Type
- Instructs the server to exclude any null ratings from the returned collection of events. By default, null-valued ratings are included.
- ex: GET /users/[uid]/events/ratings?item=42&item=70&null=false Returns all user rating events associated with items 42 and 70, excluding any null ratings.
Add New Event to User History
- POST /users/[uid]/events/ratings
- Add a new event of the specified type (In this case, a rating) to the server. If an ID is specified in the request body, the event is given the specified ID.
- Otherwise, the server generates an ID for the event and returns it in the response.
Working with Items
Add New Item to Server
- POST /items
- Adds a new item to the server. If an item ID is specified and currently unused, the item is assigned this ID. If an existing item possesses the ID, the request fails.
- If no ID is specified, one is is generated for the item by the server and returned in the response.
- The request will also return a new revision ID for use by a future update request.
Add New or Update Existing Item
- PUT /items/[iid]
- If the specified ID is unused, a new item is created and assigned the ID.
- If an existing item possesses the ID, the request must provide the item's most recent revision ID in order to update its data.
- The request will return a new revision ID for use by a future update request.
Retrieve Item Metadata
- GET /items/[iid]
- Retrieves item data from the server. This includes item attributes, but does not include the item's history of events.
Remove Item from Server
- DELETE /items/[iid]
- Deletes the item with the specified ID from the server. Precise behavior will vary between implementations.
Access Item Statistics
- GET /items/[iid]/statistics
- Retrieves common statistics regarding the specified item. Implementations are free to define their own fields.
Access Item History
Supported event types and query parameters will vary between implementations.
Basic HTTP Calls
- GET /items/[iid]/events
- Retrieves all events associated with the specified item.
- GET /items/[iid]/events/ratings
- Retrieve all events of a specific type (In this case, ratings) associated with the specified item.
Query Parameters
- user
- Required for all Event Types
- The ID of a user with which all returned events are associated. If no user ID is specified, the server will consider all possible users.
- ex: GET /items/[iid]/events/ratings?user=18&user=41 Retrieves all item rating events associated with users 18 and 41.
- history
- Required for all Event Types
- The time period during which all returned events occurred
- ex: GET /items/[iid]/events?history=1m Retrieves all events associated with the item that have occurred within the past month.
- null
- Required for the Rating Event Type
- Instructs the server to exclude null ratings. By default, null-valued ratings are included.
- ex: GET /items/[iid]/events/ratings?history=1m&null=false Returns all item ratings that have occurred within the past month, excluding any null ratings.
Working with Events
Retrieve a Specific Event
- GET /events/[eid]
- Retrieves the specified event.
- response example (JSON): {"eid":"945","uid":"516","iid":42,"timestamp":2005928682,"value":3.66}
Remove a Specific Event
- DELETE /events/[eid]
- Deletes the specified event from the server. Precise behavior will vary between implementations.
Miscellaneous
Retrieve System Statistics
- GET /statistics
- Retrieves general system-wide statistics.