跳至主要內容

RESTful APIs

小于 1 分钟

RESTful APIs

本节列出了 Gorse 服务器提供的 RESTful API。如需更多详细信息,请浏览交互式 API 文档:

http://<server_node_IP>:<server_node_port>/apidocs.

认证

默认配置下,RESTful API 不需要认证。可以通过在配置文件中设置api_key来启用认证。 API 密钥通过X-API-Key请求头传递。

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

提示

API 密钥在配置文件中设置:

[server]

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

Users API

POST /api/user

Insert a user.

Request Body

{
  "Comment": "insect",
  "Labels": [
    "crocodilia",
    "cetacean",
    "horse"
  ],
  "Subscribe": [
    "fish",
    "dog",
    "lion"
  ],
  "UserId": "cat"
}

Response Body

{
  "RowAffected": 1
}
GET /api/user/{user-id}

Get a user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to get

Response Body

{
  "Comment": "insect",
  "Labels": [
    "crocodilia",
    "cetacean",
    "horse"
  ],
  "Subscribe": [
    "fish",
    "dog",
    "lion"
  ],
  "UserId": "cat"
}
DELETE /api/user/{user-id}

Delete a user and his or her feedback.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to delete

Response Body

{
  "RowAffected": 1
}
PATCH /api/user/{user-id}

Modify a user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to modify

Request Body

{
  "Comment": "cow",
  "Labels": [
    "dog",
    "lion",
    "fish"
  ],
  "Subscribe": [
    "horse",
    "fish",
    "cat"
  ]
}

Response Body

{
  "RowAffected": 1
}
GET /api/users

Get users.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned users
cursorquerystringCursor for the next page

Response Body

{
  "Cursor": "cat",
  "Users": [
    {
      "Comment": "insect",
      "Labels": [
        "crocodilia",
        "cetacean",
        "horse"
      ],
      "Subscribe": [
        "fish",
        "dog",
        "lion"
      ],
      "UserId": "cat"
    },
    {
      "Comment": "insect",
      "Labels": [
        "crocodilia",
        "cetacean",
        "horse"
      ],
      "Subscribe": [
        "fish",
        "dog",
        "lion"
      ],
      "UserId": "cat"
    },
    {
      "Comment": "insect",
      "Labels": [
        "crocodilia",
        "cetacean",
        "horse"
      ],
      "Subscribe": [
        "fish",
        "dog",
        "lion"
      ],
      "UserId": "cat"
    }
  ]
}
POST /api/users

Insert users.

Request Body

[
  {
    "Comment": "insect",
    "Labels": [
      "crocodilia",
      "cetacean",
      "horse"
    ],
    "Subscribe": [
      "fish",
      "dog",
      "lion"
    ],
    "UserId": "cat"
  },
  {
    "Comment": "insect",
    "Labels": [
      "crocodilia",
      "cetacean",
      "horse"
    ],
    "Subscribe": [
      "fish",
      "dog",
      "lion"
    ],
    "UserId": "cat"
  },
  {
    "Comment": "insect",
    "Labels": [
      "crocodilia",
      "cetacean",
      "horse"
    ],
    "Subscribe": [
      "fish",
      "dog",
      "lion"
    ],
    "UserId": "cat"
  }
]

Response Body

{
  "RowAffected": 1
}

Items API

POST /api/item

Insert an item. Overwrite if the item exists.

Request Body

{
  "Categories": [
    "cetacean",
    "cow",
    "cow"
  ],
  "Comment": "lion",
  "IsHidden": false,
  "ItemId": "cetacean",
  "Labels": [
    "bear",
    "rabbit",
    "dog"
  ],
  "Timestamp": "2020-02-02T20:20:02.02Z"
}

Response Body

{
  "RowAffected": 1
}
GET /api/item/{item-id}

Get a item.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to get.

Response Body

{
  "Categories": [
    "cetacean",
    "cow",
    "cow"
  ],
  "Comment": "lion",
  "IsHidden": false,
  "ItemId": "cetacean",
  "Labels": [
    "bear",
    "rabbit",
    "dog"
  ],
  "Timestamp": "2020-02-02T20:20:02.02Z"
}
DELETE /api/item/{item-id}

Delete an item and its feedback.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to delete

Response Body

{
  "RowAffected": 1
}
PATCH /api/item/{item-id}

Modify an item.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to modify

Request Body

{
  "Categories": [
    "horse",
    "bear",
    "lion"
  ],
  "Comment": "insect",
  "IsHidden": false,
  "Labels": [
    "fish",
    "fish",
    "insect"
  ],
  "Timestamp": "2020-02-02T20:20:02.02Z"
}

Response Body

{
  "RowAffected": 1
}
PUT /api/item/{item-id}/category/{category}

Insert a category for a item.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to insert category
categorypathstringCategory to insert

Response Body

{
  "RowAffected": 1
}
DELETE /api/item/{item-id}/category/{category}

Delete a category from a item.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to delete categoryßßß
categorypathstringCategory to delete

Response Body

{
  "RowAffected": 1
}
GET /api/items

Get items.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned items
cursorquerystringCursor for the next page

Response Body

{
  "Cursor": "fish",
  "Items": [
    {
      "Categories": [
        "cetacean",
        "cow",
        "cow"
      ],
      "Comment": "lion",
      "IsHidden": false,
      "ItemId": "cetacean",
      "Labels": [
        "bear",
        "rabbit",
        "dog"
      ],
      "Timestamp": "2020-02-02T20:20:02.02Z"
    },
    {
      "Categories": [
        "cetacean",
        "cow",
        "cow"
      ],
      "Comment": "lion",
      "IsHidden": false,
      "ItemId": "cetacean",
      "Labels": [
        "bear",
        "rabbit",
        "dog"
      ],
      "Timestamp": "2020-02-02T20:20:02.02Z"
    },
    {
      "Categories": [
        "cetacean",
        "cow",
        "cow"
      ],
      "Comment": "lion",
      "IsHidden": false,
      "ItemId": "cetacean",
      "Labels": [
        "bear",
        "rabbit",
        "dog"
      ],
      "Timestamp": "2020-02-02T20:20:02.02Z"
    }
  ]
}
POST /api/items

Insert items. Overwrite if items exist

Request Body

[
  {
    "Categories": [
      "cetacean",
      "cow",
      "cow"
    ],
    "Comment": "lion",
    "IsHidden": false,
    "ItemId": "cetacean",
    "Labels": [
      "bear",
      "rabbit",
      "dog"
    ],
    "Timestamp": "2020-02-02T20:20:02.02Z"
  },
  {
    "Categories": [
      "cetacean",
      "cow",
      "cow"
    ],
    "Comment": "lion",
    "IsHidden": false,
    "ItemId": "cetacean",
    "Labels": [
      "bear",
      "rabbit",
      "dog"
    ],
    "Timestamp": "2020-02-02T20:20:02.02Z"
  },
  {
    "Categories": [
      "cetacean",
      "cow",
      "cow"
    ],
    "Comment": "lion",
    "IsHidden": false,
    "ItemId": "cetacean",
    "Labels": [
      "bear",
      "rabbit",
      "dog"
    ],
    "Timestamp": "2020-02-02T20:20:02.02Z"
  }
]

Response Body

{
  "RowAffected": 1
}

Feedback API

GET /api/feedback

Get feedbacks.

Parameters

NameLocateTypeDescriptionRequired
cursorquerystringCursor for the next page
nqueryintegerNumber of returned feedback

Response Body

{
  "Cursor": "fish",
  "Feedback": [
    {
      "Comment": "crocodilia",
      "FeedbackType": "bird",
      "ItemId": "fish",
      "Timestamp": "2020-02-02T20:20:02.02Z",
      "UserId": "crocodilia"
    },
    {
      "Comment": "crocodilia",
      "FeedbackType": "bird",
      "ItemId": "fish",
      "Timestamp": "2020-02-02T20:20:02.02Z",
      "UserId": "crocodilia"
    },
    {
      "Comment": "crocodilia",
      "FeedbackType": "bird",
      "ItemId": "fish",
      "Timestamp": "2020-02-02T20:20:02.02Z",
      "UserId": "crocodilia"
    }
  ]
}
PUT /api/feedback

Insert feedbacks. Existed feedback will be overwritten.

Request Body

[
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  }
]

Response Body

{
  "RowAffected": 1
}
POST /api/feedback

Insert feedbacks. Ignore insertion if feedback exists.

Request Body

[
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  }
]

Response Body

{
  "RowAffected": 1
}
GET /api/feedback/{feedback-type}

Get feedbacks with feedback type.

Parameters

NameLocateTypeDescriptionRequired
feedback-typepathstringType of returned feedbacks
cursorquerystringCursor for the next page
nqueryintegerNumber of returned feedbacks

Response Body

{
  "Cursor": "fish",
  "Feedback": [
    {
      "Comment": "crocodilia",
      "FeedbackType": "bird",
      "ItemId": "fish",
      "Timestamp": "2020-02-02T20:20:02.02Z",
      "UserId": "crocodilia"
    },
    {
      "Comment": "crocodilia",
      "FeedbackType": "bird",
      "ItemId": "fish",
      "Timestamp": "2020-02-02T20:20:02.02Z",
      "UserId": "crocodilia"
    },
    {
      "Comment": "crocodilia",
      "FeedbackType": "bird",
      "ItemId": "fish",
      "Timestamp": "2020-02-02T20:20:02.02Z",
      "UserId": "crocodilia"
    }
  ]
}
GET /api/feedback/{feedback-type}/{user-id}/{item-id}

Get feedbacks between a user and a item with feedback type.

Parameters

NameLocateTypeDescriptionRequired
feedback-typepathstringType of returned feedbacks
user-idpathstringUser ID of returned feedbacks
item-idpathstringItem ID of returned feedbacks

Response Body

{
  "Comment": "crocodilia",
  "FeedbackType": "bird",
  "ItemId": "fish",
  "Timestamp": "2020-02-02T20:20:02.02Z",
  "UserId": "crocodilia"
}
DELETE /api/feedback/{feedback-type}/{user-id}/{item-id}

Delete feedbacks between a user and a item with feedback type.

Parameters

NameLocateTypeDescriptionRequired
feedback-typepathstringType of returned feedbacks
user-idpathstringUser ID of returned feedbacks
item-idpathstringItem ID of returned feedbacks

Response Body

{
  "Comment": "crocodilia",
  "FeedbackType": "bird",
  "ItemId": "fish",
  "Timestamp": "2020-02-02T20:20:02.02Z",
  "UserId": "crocodilia"
}
GET /api/feedback/{user-id}/{item-id}

Get feedbacks between a user and a item.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringUser ID of returned feedbacks
item-idpathstringItem ID of returned feedbacks

Response Body

[
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  }
]
DELETE /api/feedback/{user-id}/{item-id}

Delete feedbacks between a user and a item.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringUser ID of returned feedbacks
item-idpathstringItem ID of returned feedbacks

Response Body

[
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  }
]
GET /api/item/{item-id}/feedback

Get feedbacks by item id.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringItem ID of returned feedbacks

Response Body

[
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  }
]
GET /api/item/{item-id}/feedback/{feedback-type}

Get feedbacks by item id with feedback type.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringItem ID of returned feedbacks
feedback-typepathstringType of returned feedbacks

Response Body

[
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  }
]
GET /api/user/{user-id}/feedback

Get feedbacks by user id.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringUser ID of returned feedbacks

Response Body

[
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  }
]
GET /api/user/{user-id}/feedback/{feedback-type}

Get feedbacks by user id with feedback type.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringUser ID of returned feedbacks
feedback-typepathstringType of returned feedbacks

Response Body

[
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  },
  {
    "Comment": "crocodilia",
    "FeedbackType": "bird",
    "ItemId": "fish",
    "Timestamp": "2020-02-02T20:20:02.02Z",
    "UserId": "crocodilia"
  }
]

Recommendation API

GET /api/item/{item-id}/neighbors

get neighbors of a item

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to get neighbors
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Response Body

[
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  }
]
GET /api/item/{item-id}/neighbors/{category}

Get neighbors of a item in category.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to get neighbors
categorypathstringCategory of returned items
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Response Body

[
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  }
]
GET /api/latest

Get the latest items.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items
user-idquerystringRemove read items of a user

Response Body

[
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  }
]
GET /api/latest/{category}

Get the latest items in category.

Parameters

NameLocateTypeDescriptionRequired
categorypathstringCategory of returned items.
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items
user-idquerystringRemove read items of a user

Response Body

[
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  }
]
GET /api/popular

Get popular items.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned recommendations
offsetqueryintegerOffset of returned recommendations
user-idquerystringRemove read items of a user

Response Body

[
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  }
]
GET /api/popular/{category}

Get popular items in category.

Parameters

NameLocateTypeDescriptionRequired
categorypathstringCategory of returned items.
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items
user-idquerystringRemove read items of a user

Response Body

[
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  }
]
GET /api/recommend/{user-id}

Get recommendation for user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to get recommendation
write-back-typequerystringType of write back feedback
write-back-delayquerystringTimestamp delay of write back feedback (format 0h0m0s)
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Response Body

[
  "bird",
  "cow",
  "crocodilia"
]
GET /api/recommend/{user-id}/{category}

Get recommendation for user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to get recommendation
categorypathstringCategory of the returned items
write-back-typequerystringType of write back feedback
write-back-delayquerystringTimestamp delay of write back feedback (format 0h0m0s)
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Response Body

[
  "cat",
  "insect",
  "horse"
]
POST /api/session/recommend

Get recommendation for session.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Request Body

[
  {
    "Comment": "rabbit",
    "FeedbackType": "rabbit",
    "ItemId": "horse",
    "Timestamp": "insect",
    "UserId": "fish"
  },
  {
    "Comment": "rabbit",
    "FeedbackType": "rabbit",
    "ItemId": "horse",
    "Timestamp": "insect",
    "UserId": "fish"
  },
  {
    "Comment": "rabbit",
    "FeedbackType": "rabbit",
    "ItemId": "horse",
    "Timestamp": "insect",
    "UserId": "fish"
  }
]

Response Body

[
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  }
]
POST /api/session/recommend/{category}

Get recommendation for session.

Parameters

NameLocateTypeDescriptionRequired
categorypathstringCategory of the returned items
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Request Body

[
  {
    "Comment": "rabbit",
    "FeedbackType": "rabbit",
    "ItemId": "horse",
    "Timestamp": "insect",
    "UserId": "fish"
  },
  {
    "Comment": "rabbit",
    "FeedbackType": "rabbit",
    "ItemId": "horse",
    "Timestamp": "insect",
    "UserId": "fish"
  },
  {
    "Comment": "rabbit",
    "FeedbackType": "rabbit",
    "ItemId": "horse",
    "Timestamp": "insect",
    "UserId": "fish"
  }
]

Response Body

[
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  }
]
GET /api/user/{user-id}/neighbors

Get neighbors of a user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to get neighbors
nqueryintegerNumber of returned users
offsetqueryintegerOffset of returned users

Response Body

[
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  },
  {
    "Id": "crocodilia",
    "Score": 3.1415926
  }
]

Health API

GET /api/health/live

Probe the liveness of this node. Return OK once the server starts.

Response Body

{
  "CacheStoreConnected": false,
  "CacheStoreError": "Nothing's Gonna Stop Us Now",
  "DataStoreConnected": false,
  "DataStoreError": "I Fall to Pieces",
  "Ready": false
}
GET /api/health/ready

Probe the readiness of this node. Return OK if the server is able to handle requests.

Response Body

{
  "CacheStoreConnected": false,
  "CacheStoreError": "Nothing's Gonna Stop Us Now",
  "DataStoreConnected": false,
  "DataStoreError": "I Fall to Pieces",
  "Ready": false
}