Common Recommender REST API

From RecSysWiki
Jump to navigation Jump to search

The MyMediaLite and LensKit projects are seeking to use a Common Recommender 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 returned, 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.

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.
The request body may also contain events related to this user.
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 each item 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","type":"rating","uid":"516","iid":42,"timestamp":2005928682,"value":3.66}
timestamp represents the seconds since the Unix epoch (UTC). Implementations may provide additional attributes to support the user's local time.

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.

External links