针对也可以属于其他资源的资源的REST API设计最佳做法

Question

为简单起见，假设我有一个用于管理项目的API，每个项目都有里程碑。里程碑属于一个项目，但我也应该能够检索所有里程碑的列表（例如显示在仪表板中）

设置路线的最合适方法是什么，这样我就可以总体上获得里程碑，也可以为特定项目获得里程碑。

GET /api/project/{id}/milestones/

或

GET /api/milestones/?projectId=123

还是完全不同的方法？

Answer 1

根据标准/最佳实践，正确的命名是：

GET /api/projects/{idProject}/milestones/

注意复数projects。这是第一个要提及的声音，用于明确指定api对待的主题。然后，您指定idProject以选择特定项目。最后，您导航到项目的sub-collection资源milestones。

如果您想进一步参考，可以找到它here。

PS：/api是剩余资源的相当普通/通用的前缀。在某些情况下可以将其省略，这是一个选择的问题。在上下文中，它实际上没有特定的含义。

Answer 2

要回答这个问题，从我的经验来看，您对两者都一视同仁

GET /api/projects/{id}/milestones/
GET /api/milestones/?projectId=123

对与错都不对，您使用的是对的，或者如果确实需要两者，则取决于项目的要求或个人喜好。

如果我要搜索跨不同项目或不同参数的里程碑，则我个人将其用作里程碑搜索终结点，例如：

GET /api/milestones/?userId=bob
GET /api/milestones/?createdDate=20180101

第一个URL我只是想获得该项目的里程碑，然后在需要的地方添加过滤器。

重新获得个人品味/项目要求