c# - RESTful API 命名资源和 Controller 设计

Question

只需阅读一些 RESTful API 设计最佳实践。我来自 ASP.Net Web 窗体背景，我一直在调用 WebMethods 背后的代码以将数据返回到我的客户端 javascript。在我看来，将这些 WebMethod 移出到一个 API 中似乎合乎逻辑，这样我们就可以开始集中化和标准化我们调用后端系统的方式。

我理解 REST 的目的是将对资源的操作归类为 GET、POST、PUT 和 DELETE。以及对这些资源使用名词而不是动词。

1)所以我有两种返回数据以生成报告的方法。由于每个报告的客户端绑定(bind)和其他特定属性，我创建了它们各自的类 BreakdownIncidents 和 BreakdownMinutes。

[WebMethod] Top10MinutesBreakdowns

|Machine|Department|Total Minutes|etc.|

[WebMethod] Top10IncidentsBreakdowns

|Machine|Department|Total Incidents|etc.|

是否应该组织这些方法:

GET /Breakdowns?report=minutes&type=top10
GET /Breakdowns?report=incidents&type=top10

然后在我的 Breakdowns Controller 中检查参数并调用适当的现有业务层函数来返回数据？

2) 报告返回两个不同的属性(简单起见:分钟数和事件数)。我真的应该将这两种方法分组到同一个 Controller 中吗？

这是我感到困惑的地方，因为报告使用不同的属性，但底层对象是分割。也许这个问题更适合重新设计我的业务对象本身。我发现我们现有的业务层有很多为绑定(bind)客户端 View 而创建的类。我确信在尝试构建此 API 时我会遇到更多这样的场景。

Answer 1

让两个调用返回不同的资源没有问题。只需将报告参数视为一种属性过滤器即可。当您不传递报告参数时，只需将这两个属性作为分割资源的一部分返回即可。

您还可以包含一个字段集参数，使返回的属性更加明确，例如:/api/breakdown?fieldset=machine,department,minutes。

如果您有许多报告，每个资源的属性各不相同，您可能会考虑类似 GraphQL 的报告，它允许您明确指定要在单个查询中返回的多个资源的属性。