如何设计API端点以发布子对象并获取所有父母的所有孩子？

例如，我有以下实体：客户，报告。客户可能有很多报告，我认为单个报告管理的端点应该像这样嵌套：

/clients/{client_id}/reports/{report_id}

至于一位客户的所有报告，预期会：

/clients/{client_id}/reports

但是应该如何寻找一个端点来获取所有客户端的所有报告，以保持API的一致性和良好的设计。

我的方法：

1. （我在某些Google API中看到了它）使用“-”代替它，并将其解析为“全部”：

/clients/-/reports

这使端点格式保持不变，但看起来有点不正常，找不到任何以此方式建议的rfc。

2. 为所有报告创建一个单独的端点：

/reports

但是要获得客户报告，它仍然是：

/clients/{client_id}/reports

3. 重构端点以使“客户端”不是父代，而只是一个过滤器参数：

/reports?client={client_id} -一位客户的报告

/reports -所有客户的报告

如果添加新的端点以发布特定客户端的报告，则该外观可能很难看，因为它将是带有URL中参数的POST请求。

还有其他建议吗？

但是应该如何寻找一个端点来获取所有客户端的所有报告，以保持API的一致性和良好的设计。

在进行其他任何操作之前，请记住，没有建模RESTful API的黄金法则。我们所拥有的都是最佳实践和惯例。话虽如此，可能的答案是-像往常一样-选择最能满足您的需求的答案，在这种情况下，最能表达您的模型的答案。

因此，从表现力上检查三个选项。

＃1“-”表示法

这是一个好主意。它使我们能够表达所有reports属于clients的条件。它将“查询”的范围缩小到一组特定的报告（位于clients边界内的报告）。

它始终保持层次结构（所属）的概念，因此，如果reports可以在不同的位置找到它，那么这个概念就很重要了。例如：

• 属于客户的所有报告 /clients/-/reports
• 属于部门的所有报告 /departments/-/reports
• 所有属于员工的报告 /employees/-/reports

但是，要检索系统中所有可用的报告，保持层次结构不会比下一个选项提供任何有价值的优势。

＃2不同的URI

如果在检索所有可用报告时不需要表达边界/上下文/层次结构，那么这种方法对我来说似乎更合理。

新的URI（/reports）还为报表管理留下了可能性。但是，如果我们认为没有必要，则不必为它提供完整的RESTful支持。例如，您已声明Make a separate endpoint just for all the reports。很好，您只需实现即可GET，也许还可以使用一些过滤器进行查询，仅此而已。

请注意，您仍然可以这样做/reports?client={client_id}。对于相同的资源使用不同的URI很好。我读过的一些文章称这种鲁棒性。

＃3恢复层次结构

我感到这种方法不能满足您的期望。另外，我认为，它将最终带您进入起点。

结论

注意，＃1和＃2并不互斥。我们可以同时实现。考虑到实际情况，并根据OP的前提，我将仅执行＃2。

^{1：相当于/clients/-/reports我猜}

Google的API设计模式建议在这种情况下使用“-”。

GET /clients/-/reports

资源：

https://cloud.google.com/apis/design/design_patterns#list_sub-collections