GET all parent resource 的响应体是否应该返回子资源列表？答案

【问题标题】：Should the response body of GET all parent resource return a list of child resource?GET all parent resource 的响应体是否应该返回子资源列表？
【发布时间】：2018-05-09 14:12:27
【问题描述】：

如果标题有点混乱，请多多包涵，我会尽力在下面解释我的问题。

假设我有以下两个端点

api/companies（返回如下所有公司的列表）

[{name: "company1", id: 1}, {name: "company2", id: 2}]
api/companies/{companyeId}/employees（返回特定公司的所有员工列表，如下所示）

[{name: "employee1", id: 1}, {name: "employee2", id: 2}]

客户端需要的是一份公司名单，每家公司都有一份员工名单。结果应如下所示：

[
  {
    name: "company1", 
    id: 1, 
    employees: [ {name: "employee1", id: 1}, {name: "employee2", id: 2} ]
  },
  {
    name: "company2", 
    id: 2, 
    employees: [ {name: "employee3", id: 3}, {name: "employee4", id: 4} ]
  },    
]

我可以想到两种方法来做到这一点：

先获取公司列表，循环遍历公司列表为每家公司进行 api 调用以获取其员工列表。（如果我理解正确，我想知道这是否是一种更好的设计方式，因为HATEOAS 原则？因为api/companies 的最小资源单位是公司而不是员工，所以客户应该发现公司作为可用资源但不是员工。）

REST 客户端应该能够动态使用服务器提供的链接来发现它需要的所有可用操作和资源

返回每个公司对象内的员工列表，然后通过api/companies 返回公司列表。可能会向此端点添加一个名为responseHasEmployees 的查询参数，这是一个布尔默认值为false，因此当用户通过api/companies?responseHasEmployees=true 进行GET 时，响应正文将在每个公司对象中包含一个员工列表。

所以我的问题是，哪种方式是实现客户端目标的更好方式？（不一定非得是以上两个。）

可能有帮助的额外信息：公司和员工存储在不同的表中，员工表有一个company_fk 列。

【问题讨论】：

标签： sql rest api

【解决方案1】：

首先问自己几个问题：

这是常见的情况吗？
以这种方式请求数据合乎逻辑吗？

如果是这样，以这种方式提供数据可能是有意义的。

接下来，您是否已经实现了传递变量的 api 调用？根据您的 HATEOAS 原则，您可能不应该这样做。客户不需要知道或理解您网址中的变量值。如果没有，请远离它。使其对客户端尽可能干净。您可以制作第三个不同的 api “api/companiesWithEmployees” 这符合您的 HATEOAS 原则，客户端不需要了解任何有关参数或其他 api 工作原理的信息，只要他们会得到“有员工的公司”。此外，成本最低；代码库中的附加方法。对客户端来说更简单，成本更低。

接下来考虑一些发展后果：您是否正在为更具体的 api 请求打开大门？
您能否对希望通过 api 访问的数据保持强硬态度？
您是否能够保持您的 HATEOAS 原则，因为客户根据 api url 知道他们需要知道的一切？

接下来将这样的场景融入未来的 api 设计中：你能抢先让类似的api调用可用吗？即（客户和订单，您是否只需提供一个可用的 api 调用来使两者相互关联？）

最终，我对您的问题的回答是继续进行新的 api 调用。设置、测试和维护此特定更改的开销似乎非常小，并且以这种方式请求数据的可能性似乎很高。

【讨论】：

【解决方案2】：

我假设您构建的客户端将有一个界面来查看公司列表，其中可以选择查看公司员工。所以最好是按需拉取，而不是一次加载整个数据。

如果您可以将资源的某个属性视为子资源，请不要将整个子资源数据添加到主资源 API 中。您可以包含一个推荐链接，客户端可以使用该链接来获取子资源数据。

这里，在你的情况下，

主要资源 - 公司
子资源 - 员工

公司名称、联系电话、地址 - 这些是公司对象的属性，而不是公司的子资源，而员工可以很好地被视为子资源。

【讨论】：