如何更正 REST 中的模型“摘要”？

Question

微服务公开了一个规范的 REST API 来处理两种资源：teams 和 matches，其中一场比赛由两支球队进行并有一个分数。

1. post /team 将添加一个新团队
2. get /teams 将获得所有团队
3. get /team/{id} 将返回一个特定的团队

为match 资源提供了相同的规范实现。现在，这个微服务有两个客户端应用：

• 一个公共网站，需要显示每支球队的总比赛场数、总胜场数和总负数
• 一个私人网站，需要显示最大损失和获得最多红牌的球员

让我们添加以下约束：

1. 我们不希望在 team 资源中返回此摘要信息，因为它的计算成本可能很高
2. 两个摘要有不同的权限：根据 HTTP 请求中的标头，我们可能会接受/拒绝请求

为这个用例设计 API 的合适方法是什么？

• 带有查询参数的单个端点，不会导致端点数量激增，但返回的响应彼此非常不同

• 多个端点（内部汇总、外部汇总、分数汇总、故障汇总）

Answer 1

您可能知道，在规范的 REST API 设计中，路径参数和查询参数用于不同的目的：

路径：标识特定资源/资源，
查询：排序/过滤 资源。

在您的用例中，我们必须处理汇总数据，这可以看作是一种不同的资源，因为通常它包含的数据与您的 /teams 和 /matches 路径中的数据性质不同。

在我看来，这个用例的一个好的设计可能是做一个 /stats 路径，然后 通过查询参数过滤它（匹配、获胜、错误、. ..)，这有助于清晰并且不会使 api 过于复杂，将来您还可以通过简单和可维护的方式轻松添加更多统计资源。