RESTful API命名资源和控制器设计

Question

仅阅读一些RESTful API设计最佳实践。 我来自ASP.Net Web窗体背景，在这里我一直在WebMethods后面调用代码以将数据返回到客户端JavaScript。 在我看来，将这些WebMethods移到API中似乎是合乎逻辑的，因此我们可以开始集中化和标准化我们如何调用后端系统。

我知道REST的目的是将对资源的操作分类为GET，POST，PUT和DELETE。 对于这些资源，也可以使用名词代替动词。

1）因此，我有两种方法可以返回数据以生成报告。 由于客户端绑定和每个报表的其他特定属性，我创建了各自的类BreakdownIncidents和BreakdownMinutes。

[WebMethod] Top10MinutesBreakdowns

|Machine|Department|Total Minutes|etc.|

[WebMethod]十大突发事件细分

|Machine|Department|Total Incidents|etc.|

是否应组织以下方法：

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

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

2）报告返回两个不同的属性（为简单起见：分钟数和事件数）。 我是否应该将这两种方法归为同一个控制器？

这是我感到困惑的地方，因为报表使用了不同的属性，但是基础对象是细分。 也许这个问题更适合于我的业务对象本身的重新设计。 我发现我们现有的业务层具有许多用于绑定客户端视图的类。 我肯定在尝试构建此API时会遇到更多这些情况。

Answer 1

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

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

如果您有许多报表，每个资源的属性种类繁多，则可以考虑使用诸如GraphQL之类的图形 ，它允许您显式指定多个资源的属性以在单个查询中返回。

Answer 2

我知道REST的目的是将对资源的操作分类为GET，POST，PUT和DELETE。 对于这些资源，也可以使用名词代替动词。

并非如此-REST的目标是阐明支持Web规模应用程序所需的约束。 参见菲尔丁，2000年

这是我感到困惑的地方，因为报表使用了不同的属性，但是基础对象是细分。

不要将您的API与基础实现/表示混淆。 Top10MinutesBreakdowns和Top10IncidentsBreakdowns 信息资源碰巧使用对同一基础对象的引用，这是您当前实现的意外情况。

换句话说，您的控制器是适配器，支持幻觉只是一个理解HTTP请求消息的文档存储。

选择在同一控制器或不同控制器中支持这两个报告，实际上取决于诸如这些报告相对于彼此更改的频率，自定义将请求路由到适当控制器的成本等。

您可以正确路由的任何URI拼写都可以，但我个人倾向于提供这些报告的标识符。

GET /Top10MinutesBreakdowns
GET /Top10IncidentsBreakdowns

然后配置您的路由以将那些请求传递到适当的控制器。