REST API 设计 - 使用 ETag 将集合作为数组

Question

采取以下网址模板：

~/pupil/{id}/subjects

如果主题是一个以传统方式表示的集合，就好像每个项目都像瞳孔项目一样独立存在，那么这是暴露它们的正确方式吗？

当您考虑根据瞳孔更新集合并与另一个 API 调用者同时更新集合时，您会开始感到不对劲。

突然之间，您无法同步访问，因为没有 ETag 可以覆盖该集合，您最终会交错更改并陷入混乱。

不同的设计可以将主题作为子数组合并到瞳孔的实体中，/subjects URL 仅用于读取访问。

也许主题应该作为带有谨慎 ETag 的单个数组集实体返回，并且应该禁用发布单个主题并通过整个集合的 POST/PUT 进行更新，但是如果列表很长怎么办？需要分页吗？

也许设计决策是根据具体情况而定的，而不是笼统的指导方针。不确定。

想法？

Answer 1

这取决于您是否要将“主题”视为单一资源。

如您所说，如果您的 API 的消费者想要添加、删除或修改单个主题，那么就 REST 模式而言，表示它们的传统方式是正确的：

~/pupil/{id}/subjects

将返回资源列表

~/pupil/{id}/subjects/{subjectId}

除非有充分的理由优化批量操作或缓存，否则这是最 RESTful 和最直接的实现。