RESTful APIs

2022/12/19大约 8 分钟

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] 部分设置：

[server]

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

API 接口

GET /api/collaborative-filtering/{user-id} 获取用户的协同过滤推荐。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID
n	query	integer	返回物品的数量
offset	query	integer	返回物品的偏移量
category	query	string	返回物品的类别。
user-id	query	string	移除用户已读物品

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/feedback 列出反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
cursor	query	string	下一页的游标
n	query	integer	返回反馈的数量

Response:

{
  "Cursor": "string",
  "Feedback": [
    {
      "Comment": "string",
      "FeedbackType": "string",
      "ItemId": "string",
      "Timestamp": "2000-01-01T00:00:00Z",
      "Updated": "2000-01-01T00:00:00Z",
      "UserId": "string",
      "Value": 0
    }
  ]
}

PUT /api/feedback 插入反馈。现有的反馈将被覆盖。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥

Body:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

Response:

{
  "RowAffected": 0
}

POST /api/feedback 插入反馈。如果反馈已存在，则累加值。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥

Body:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

Response:

{
  "RowAffected": 0
}

GET /api/feedback/{feedback-type} 列出指定类型的反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
feedback-type	path	string	反馈类型
cursor	query	string	下一页的游标
n	query	integer	返回反馈的数量

Response:

{
  "Cursor": "string",
  "Feedback": [
    {
      "Comment": "string",
      "FeedbackType": "string",
      "ItemId": "string",
      "Timestamp": "2000-01-01T00:00:00Z",
      "Updated": "2000-01-01T00:00:00Z",
      "UserId": "string",
      "Value": 0
    }
  ]
}

GET /api/feedback/{feedback-type}/{user-id}/{item-id} 获取用户和物品之间指定类型的反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
feedback-type	path	string	反馈类型
user-id	path	string	用户 ID
item-id	path	string	物品 ID

Response:

{
  "Comment": "string",
  "FeedbackType": "string",
  "ItemId": "string",
  "Timestamp": "2000-01-01T00:00:00Z",
  "Updated": "2000-01-01T00:00:00Z",
  "UserId": "string",
  "Value": 0
}

DELETE /api/feedback/{feedback-type}/{user-id}/{item-id} 删除用户和物品之间指定类型的反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
feedback-type	path	string	反馈类型
user-id	path	string	用户 ID
item-id	path	string	物品 ID

Response:

{
  "RowAffected": 0
}

GET /api/feedback/{user-id}/{item-id} 列出用户和物品之间的反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID
item-id	path	string	物品 ID

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

DELETE /api/feedback/{user-id}/{item-id} 删除用户和物品之间的反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID
item-id	path	string	物品 ID

Response:

{
  "RowAffected": 0
}

GET /api/health/live 探测此节点的存活状态。服务器启动后返回 OK。

Parameters: None

Response:

{
  "CacheStoreConnected": false,
  "CacheStoreError": {},
  "DataStoreConnected": false,
  "DataStoreError": {},
  "Ready": false
}

GET /api/health/ready 探测此节点的就绪状态。如果服务器能够处理请求，则返回 OK。

Parameters: None

Response:

{
  "CacheStoreConnected": false,
  "CacheStoreError": {},
  "DataStoreConnected": false,
  "DataStoreError": {},
  "Ready": false
}

POST /api/item 插入一个物品。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥

Body:

{
  "Categories": [
    "string"
  ],
  "Comment": "string",
  "IsHidden": false,
  "ItemId": "string",
  "Labels": {},
  "Timestamp": "2000-01-01T00:00:00Z"
}

Response:

{
  "RowAffected": 0
}

GET /api/item-to-item/{name}/{item-id} 获取物品到物品的推荐。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
name	path	string	物品到物品推荐的名称
item-id	path	string	物品 ID
n	query	integer	返回物品的数量
offset	query	integer	返回物品的偏移量
category	query	string	返回物品的类别
user-id	query	string	移除用户已读物品

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/item/{item-id} 获取一个物品。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
item-id	path	string	物品 ID.

Response:

{
  "Categories": [
    "string"
  ],
  "Comment": "string",
  "IsHidden": false,
  "ItemId": "string",
  "Labels": {},
  "Timestamp": "2000-01-01T00:00:00Z"
}

DELETE /api/item/{item-id} 删除一个物品及其反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
item-id	path	string	物品 ID

Response:

{
  "RowAffected": 0
}

PATCH /api/item/{item-id} 修改一个物品。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
item-id	path	string	物品 ID

Body:

{
  "Categories": [
    "string"
  ],
  "Comment": "string",
  "IsHidden": false,
  "Labels": {},
  "Timestamp": "2000-01-01T00:00:00Z"
}

Response:

{
  "RowAffected": 0
}

PUT /api/item/{item-id}/category/{category} 为物品插入一个类别。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
item-id	path	string	物品 ID
category	path	string	要插入的类别

Response:

{
  "RowAffected": 0
}

DELETE /api/item/{item-id}/category/{category} 从物品中删除一个类别。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
item-id	path	string	物品 ID
category	path	string	要删除的类别

Response:

{
  "RowAffected": 0
}

GET /api/item/{item-id}/feedback 根据物品 ID 获取反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
item-id	path	string	物品 ID

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

GET /api/item/{item-id}/feedback/{feedback-type} 根据物品 ID 和反馈类型获取反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
item-id	path	string	物品 ID
feedback-type	path	string	反馈类型

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

GET /api/item/{item-id}/neighbors 获取物品的邻居。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
item-id	path	string	物品 ID
n	query	integer	返回物品的数量
offset	query	integer	返回物品的偏移量
category	query	string	返回物品的类别
user-id	query	string	移除用户已读物品

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/items 列出物品。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
n	query	integer	返回物品的数量
cursor	query	string	下一页的游标

Response:

{
  "Cursor": "string",
  "Items": [
    {
      "Categories": [
        "string"
      ],
      "Comment": "string",
      "IsHidden": false,
      "ItemId": "string",
      "Labels": {},
      "Timestamp": "2000-01-01T00:00:00Z"
    }
  ]
}

POST /api/items 插入物品。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥

Body:

[
  {
    "Categories": [
      "string"
    ],
    "Comment": "string",
    "IsHidden": false,
    "ItemId": "string",
    "Labels": {},
    "Timestamp": "2000-01-01T00:00:00Z"
  }
]

Response:

{
  "RowAffected": 0
}

GET /api/latest 获取最新物品。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
category	query	string	返回物品的类别
n	query	integer	返回物品的数量
offset	query	integer	返回物品的偏移量
user-id	query	string	移除用户已读物品

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/non-personalized/{name} 获取非个性化推荐。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
category	query	string	返回物品的类别。
n	query	integer	返回用户的数量
offset	query	integer	返回用户的偏移量
user-id	query	string	移除用户已读物品

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/recommend/{user-id} 获取用户的推荐。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID
category	query	string	返回物品的类别（支持多类别过滤）
write-back-type	query	string	回写反馈的类型
write-back-delay	query	string	回写反馈的时间戳延迟（格式 0h0m0s）
n	query	integer	返回物品的数量
offset	query	integer	返回物品的偏移量

Response:

[
  "string"
]

POST /api/session/recommend 获取会话的推荐。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
n	query	integer	返回物品的数量
offset	query	integer	返回物品的偏移量

Body:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "string",
    "UserId": "string",
    "Value": 0
  }
]

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

POST /api/user 插入一个用户。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥

Body:

{
  "Comment": "string",
  "Labels": {},
  "UserId": "string"
}

Response:

{
  "RowAffected": 0
}

GET /api/user-to-user/{name}/{user-id} 获取用户到用户的推荐。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
name	path	string	用户到用户推荐的名称
user-id	path	string	用户 ID
n	query	integer	返回用户的数量
offset	query	integer	返回用户的偏移量

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/user/{user-id} 获取一个用户。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID

Response:

{
  "Comment": "string",
  "Labels": {},
  "UserId": "string"
}

DELETE /api/user/{user-id} 删除一个用户。他/她的反馈也将被删除。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID

Response:

{
  "RowAffected": 0
}

PATCH /api/user/{user-id} 修改一个用户。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID

Body:

{
  "Comment": "string",
  "Labels": {}
}

Response:

{
  "RowAffected": 0
}

GET /api/user/{user-id}/feedback 根据用户 ID 获取反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

GET /api/user/{user-id}/feedback/{feedback-type} 根据用户 ID 和反馈类型获取反馈。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID
feedback-type	path	string	反馈类型

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

GET /api/user/{user-id}/neighbors 获取用户的邻居。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
user-id	path	string	用户 ID
n	query	integer	返回用户的数量
offset	query	integer	返回用户的偏移量

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/users 列出用户。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥
n	query	integer	返回用户的数量
cursor	query	string	下一页的游标

Response:

{
  "Cursor": "string",
  "Users": [
    {
      "Comment": "string",
      "Labels": {},
      "UserId": "string"
    }
  ]
}

POST /api/users 插入用户。

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API 密钥

Body:

[
  {
    "Comment": "string",
    "Labels": {},
    "UserId": "string"
  }
]

Response:

{
  "RowAffected": 0
}