RESTful API 设计：检索类别中的项目数

Question

我想创建一个 REST API，其中包含类别中的项目，并列出所有类别及其项目数量。

架构：

Category {id, name}
Item {id, name, categoryId}

端点：

GET    /categories/list
GET    /categories/<id>
PUT    /categories/<id>

GET    /items/list[?category=<categoryId>]
GET    /items/<id>

要更新我从GET /categories/<id> 获得的内容，修改JSON 对象并返回PUT。

到目前为止一切顺利。

我的问题是是否有一种或多种最佳做法来检索项目计数？ 我可以想到几种方法来做到这一点：

1. 为每个类别触发一个GET /items/list?category=<categoryId>，计算结果项。
   从X-total-count 或content range 标头或从端点返回的total_count 字段中获取计数将避免必须实际加载所有项目。
2. 将item_count 字段添加到生成的JSON 类别对象中。
   对于PUTs，应该如何处理这个只读字段？让后端忽略它？手动取消设置？
3. 创建一个专用端点/categories/item_counts，它返回一个包含每个项目数的类别列表。

我喜欢选项 2（例如 the wordpress API does it this way），因为它不需要额外的请求。但我真的不喜欢为 GET 和 PUT 请求使用不同的对象结构的想法。

Answer 1

REST 实际上是关于对象的表示。 Category 没有计数，因为它是单个对象。出于同样的原因，Item 也没有计数。 Count 更像是 RPC，你告诉服务计算一些东西。

GET /items/list[?category=<categoryId>]

类似于 RPC，将category 参数传递给list 方法。保持这种习惯，您可以“链接”这些方法来获取指定类别中的项目总数：

GET /items/list/count[?category=<categoryId>]

虽然我会改用路径参数：

GET /items/list/<category_id>/count

但list 是隐含的，因此您可以将其删除：

GET /items/<category_id>/count

它与“纯” REST 有点偏离，但它使您的实际 REST 对象保持清洁，正如您所说，保持 total_count 我们的 Category 对象。

我假设您有时需要计数，但不是所有 Items，否则您不需要向 API 询问计数，您只需在客户端中自己计算它们。这暗示了另一种选择：

GET /categories/<id>/count
{
  "total_count": 10
}

这更适合找出 Category 中有多少 Items 的用例。