Question

我们来看下面的例子：

我们希望从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标准，那么采取这种情况的最佳方法是什么？

Answer 1

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

您的第一个解决方案一开始似乎很好，但只要您想要访问关系本身就会遇到问题。

不应使用以下GET请求返回员工，而应返回该关系。

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

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

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

在这种情况下，我会想出一个单独的关系资源：

获取api / v1 / company-employees / {id}

JSON中返回的模型如下所示：

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

Answer 2

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

Answer 3

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

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

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

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

是否使用子资源？

解决方案1：使用子资源

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

3 个答案: