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. 在结果类别JSON对象中添加一个item_count字段。
   应如何处理PUT的只读字段？使后端忽略它？手动取消设置？
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个对象。

我假设您有时需要计数，但并非所有Item都需要计数，否则您不需要向API询问计数，您只需自己在客户端中计数即可。这表明了另一种选择：

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

这更适合于找出Item中有多少Category个用例的情况。