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.


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


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

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

curl -H "X-API-Key: *****"

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:


# 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.


# 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-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

POST/itemInsert 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/itemsInsert items. Overwrite if items exist.
GET/itemsGet 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

POST/userInsert 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/usersGet users.

Feedback APIs

POST/feedbackInsert feedbacks.
Ignore if exists.
PUT/feedbackInsert feedbacks.
Overwrite if exists.
GET/feedbackGet 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}/feedbackGet feedback by user id.
GET/user/{user-id}/feedback/{feedback-type}Get feedbacks by user id
with feedback type.
GET/item/{item-id}/feedbackGet feedback by item id.
GET/item/{item-id}/feedback/{feedback-type}Get feedbacks by item id
with feedback type.

Recommendation APIs

GET/popularGet popular items.
GET/popular/{category}Get popular items in category.
GET/latestGet latest items.
GET/latest/{category}Get latest items in category.
GET/item/{item-id}/neighborsGet neighbors of an item.
GET/item/{item-id}/neighbors/{category}Get neighbors of an item in category.
GET/user/{user-id}/neighborsGet 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/recommendGet recommendations based on session (a list of feedbacks).