Common Recommender REST API

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")

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 to Server

POST /users

Adds a new user to the server. An ID is generated by the server and returned in the response.

PUT /users/[uid]

Adds a new user, with a client-defined ID, to the server.

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.

ex: GET /users/predictions?item=42&item=70 Retrieves user rating predictions for items 42 and 70.

ratingOverride

Enables the server to return a user rating rather than a prediction if one has been provided for an item.

ex: GET /users/predictions?ratingOverride=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

Supported event types and query parameters will vary between implementations.

Basic HTTP Calls

GET /users/[uid]/events

Retrieves all events associated with the specified user.

GET /users/[uid]/events/ratings

Retrieve all events of a specific type (In this case, ratings) associated with the specified user.

GET /users/[uid]/ratings

Retrieves a vector containing the most recent rating of all items rated by the user.

Query Parameters

item

The ID of an item with which all returned events are associated.

ex: GET /users/[uid]/events/ratings?item=42&item=70 Retrieves all user rating events associated with items 42 and 70.

history

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.

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. The event's ID is returned in the response.

Working with Items

Add New Item to Server

POST /items

Adds a new item to the server. An ID is generated by the server and returned in the response.

PUT /items/[iid]

Adds a new item, with a client-defined ID, to the server.

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

The ID of a user with which all returned events are associated.

ex: GET /items/[iid]/events/ratings?user=18&user=41 Retrieves all item rating events associated with users 18 and 41.

history

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.

Working with Events

Retrieve a Specific Event

GET /events/[eid]

Retrieves the specified event.

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.