是否使用子资源？

Posted 2023-03-31

【中文标题】是否使用子资源？

【英文标题】：Using a sub-resource or not?

【发布时间】：2014-11-07 06:55:43

【问题描述】：

我们来看下面的例子：

我们希望通过 RESTful API 公开公司和员工信息。

公司数据应该很简单：

GET api/v1/companies
GET api/v1/companies/id

员工属于一家公司，但我们仍想单独检索他们，那么哪种解决方案最好：

解决方案 1：使用子资源

获取公司的所有员工：

GET api/v1/companies/companyId/employees

获取特定员工：

GET api/v1/companies/companyId/employees/employeeId

解决方案 2：使用独立资源

获取公司的所有员工：

GET api/v1/employees?companyId=companyId

获取特定员工：

GET api/v1/employees/employeeId

这两种选择似乎各有利弊。

对于子资源，当我想要检索单个员工时，我可能并不总是手头有 CompanyId。

有了独立资源，如果我们想要 RESTful，让公司的所有员工都应该使用子资源方法。

否则，我们可以使用混合，但这缺乏一致性：

获取公司的所有员工：

GET api/v1/companies/companyId/employees

获取特定员工：

GET api/v1/employees/employeeId

如果我们想忠于 RESTful 标准，在这种情况下采取什么最佳方法？

【参考方案1】：

对我来说，这听起来像是 RESTful 服务常见的多对多关系问题。 （见How to handle many-to-many relationships in a RESTful API?）

您的第一个解决方案一开始看起来不错，但只要您想访问关系本身就会遇到问题。

您应该返回关系，而不是通过以下 GET 请求返回员工。

获取 api/v1/companies/companyId/employees/employeeId

如果可以通过 2 个键来识别关系，则此解决方案似乎没问题。但是如果关系由 3+ id 标识会发生什么？ URI 变得相当长。

GET api/v1/companies/companyId/employees/employeeId/categories/categoryId

在这种情况下，我会为关系提供一个单独的资源：

GET api/v1/company-employees/id

以 JSON 格式返回的模型如下所示：

   "id": 1 <- the id of the relation
   "company": 
      "id": 2
   ,
   "employee": 
      "id": 3
   ,
   "category": 
      "id": 4
   

【参考方案2】：

我认为两者都提供是可以的。如果您希望客户端先浏览公司列表，然后选择一家公司，然后获取所有员工的列表，则第一种方法是必要的。此外，如果您希望客户能够按姓名或年龄过滤员工，但不知道公司标识符，您还必须提供第二种方法。这取决于您希望客户做什么。在我看来，如果客户只能按公司标识符过滤员工，则没有必要提供第二种方法。

【参考方案3】：

我会采用第一种方法并提供一些链接来检索从属资源。

如果我以您可能在公司中添加的新员工为例。对于使用第二种方法的客户来说，在您的集合上进行 POST 似乎很困难。为什么 ？因为他必须知道“其他地方”的公司ID。 使用第一种方法时，当您遵循某个路径时，您已经知道此信息（companyId）......因此客户可以更轻松地添加新员工。

回到您的示例，第二种方法的主要好处是，如果您的客户想要“一个城市的员工数量”之类的东西，而您并不关心公司的概念。 不过看来你需要公司的概念，所以我会选择第一个。

另外，与这个问题非常相关：RESTful design: when to use sub-resources?