rest - 是否使用子资源？

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}

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

GET api/v1/company-employees/{id}

返回的 JSON 模型如下所示:

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