是否使用子资源？

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 服务常见的多对多关系问题。（请参阅如何在 RESTful API 中处理多对多关系？）

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

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

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

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

获取 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
   }
}