Gorse Docs

# RESTful APIs

RESTful APIs provided by the Gorse server are listed in this section. For more detailed information, please browse the interactive API document at http://<server node IP>:<server node port>/apidocs.

# Authorization

By default, there is no authorization required for RESTful APIs. Authorization can be enabled by set api_key in config file:

[server]

# Secret key for RESTful APIs (SSL required).
api_key = "*****"

The API key is passed through X-API-Key header.

curl -H "X-API-Key: *****"  http://127.0.0.1:8087/api/recommend/bob?n=10

# Default Length of Returned List

There are RESTful APIs returns collections (users, items or feedbacks). The default number of returned elements is specified in configuration file:

[server]

# Default number of returned items. The default value is 10.
default_n = 10

# Clock Error

Gorse use timestamps to invalid recommended items and etc.. However, clocks on different nodes might differ from each other. The maximal clock error is specified in config file to ensure the system works properly.

[server]

# Clock error in the cluster. The default value is 5s.
clock_error = "5s"

# Server-side Cache

The serer node is responsible to filter out hidden items or deleted items from cache and insert popular items to new categories. There is a server-side cache for hidden items and popular items from v0.4.1 to reduce the load of cache database. The freshness of cache is specified by cache_expire under [server].

[server]

# Server-side cache expire time. The default value is 10s.
cache_expire = "10s"

The cache_expire is the time that a item recovers from hidden state. It has no affect on updating popular items or hiding items.

# Item APIs

Method URL Description
POST /item Insert an item.
Overwrite if the item exists.
GET /item/{item-id} Get an item.
PATCH /item/{item-id} Modify an item.
DELETE /item/{item-id} Delete an item and its feedbacks.
POST /items Insert items. Overwrite if items exist.
GET /items Get items.
PUT /item/{item-id}/category/{category} Append a category to an item.
DELETE /item/{item-id}/category/{category} Delete a category from an item.

# User APIs

Method URL Description
POST /user Insert a user. Overwrite if the user exists.
GET /user/{user-id} Get a user.
PATCH /user/{user-id} Modify a user.
DELETE /user/{user-id} Delete a user and his or her feedbacks.
GET /users Get users.

# Feedback APIs

Method URL Description
POST /feedback Insert feedbacks.
Ignore if exists.
PUT /feedback Insert feedbacks.
Overwrite if exists.
GET /feedback Get feedbacks.
GET /feedback/{feedback-type} Get feedbacks with
feedback type.
GET /feedback/{user-id}/{item-id} Get feedbacks between
a user and a item.
DELETE /feedback/{user-id}/{item-id} Delete feedbacks between
a user and a item.
GET /feedback/{feedback-type}/{user-id}/{item-id} Get feedbacks between
a user and a item
with feedback type..
DELETE /feedback/{feedback-type}/{user-id}/{item-id} Delete feedbacks between
a user and a item
with feedback type..
GET /user/{user-id}/feedback Get feedback by user id.
GET /user/{user-id}/feedback/{feedback-type} Get feedbacks by user id
with feedback type.
GET /item/{item-id}/feedback Get feedback by item id.
GET /item/{item-id}/feedback/{feedback-type} Get feedbacks by item id
with feedback type.

# Recommendation APIs

Method URL Description
GET /popular Get popular items.
GET /popular/{category} Get popular items in category.
GET /latest Get latest items.
GET /latest/{category} Get latest items in category.
GET /item/{item-id}/neighbors Get neighbors of an item.
GET /item/{item-id}/neighbors/{category} Get neighbors of an item in category.
GET /user/{user-id}/neighbors Get neighbors of a user.
GET /recommend/{user-id} Get recommendations for a user.
GET /recommend/{user-id}/{category} Get recommendations for a user
in category.
POST /session/recommend Get recommendations based on session (a list of feedbacks).

← Configuration →