rest - RESTful API路由设计:嵌套与非嵌套

Question

我的问题是在构建用于API的URL时嵌套资源的优势。考虑以下两种替代方法来访问员工资源:

/api/employees?department=1   # flat

Vs.

/api/departments/1/employees  # nested

现在考虑开发通用库以从API访问REST资源的任务。如果所有路由都是平坦的，则这样的REST包装器库只需要知道所访问资源的名称即可:

store.query('employees', {department_id:1})   =>   /api/employees?department=1

但是，如果我们要支持嵌套路由，则此包装器将需要知道有关嵌套哪些模型以及在其他资源下嵌套的其他信息，以便知道如何构建引用此类模型的URL。鉴于并非所有模型都嵌套在同一父资源下，甚至根本不嵌套某些模型，因此REST包装器库将需要具有某种配置，以描述所有这些本来不需要的额外知识。

所以我的问题是:

API中的嵌套资源路由有真正的优势吗？ (这并不意味着要由最终用户使用，因此从更漂亮的URL中获得的 yield 更少)。

嵌套方法是否真的比平面方法好，而且美观之外，以便证明为支持资源URL构建缺乏统一性而付出的额外努力和复杂性是合理的？

另请参阅: https://stackoverflow.com/a/36410780/621809

更新:重要说明

我从一些评论和答案中意识到，对于一个方面我还不够清楚:我不反对使用 /employees/5或 /departments/1这样的URL来寻址单个资源。我不认为这是嵌套的。

当我说嵌套资源时，我指的是像 /departments/1/employees这样的URL，其中总是在另一个资源的上下文中对资源进行寻址。主要的问题是，用于URL构建的 (通用库)需要知道额外的东西，例如“雇员嵌套在部门之下”，而“分支机构不嵌套在任何事物之下”。如果所有资源都可以RESTful地(但以统一的方式)解决，那么知道如何解决它们将更简单，更可预测。

当您考虑它时，在数据库中，您不需要了解其他信息即可知道如何寻址对象的集合(例如RDMS中的表)。您始终将员工集合称为 employees，而不是 departments/5/employees。

Answer 1

如果您想进一步追溯几个级别，会发生什么？
/api/addresses?departmentId=1&employeeId=2&addressId=3
与
/api/departments/1/employees/2/addresses/3
地址端点突然变得充满了参数。

另外，如果您正在查看Richardson Maturity Model level 3，则可以通过链接发现RESTful API。例如，在顶层，例如/ api / version(/ 1)，您会发现有一个到部门的链接。这是在类似HAL浏览器的工具中的外观:

"api:department-query": {
  "href": "http://apiname:port/api/departments?pageNumber={pageNumber}&pageSize={pageSize}&sort={sort}"
},
"api:department-by-id": {
  "href": "http://apiname:port/api/departments?departmentId={departmentId}"
}

(可以最终以页面方式列出所有查询的查询，也可以是直接进入特定部门的参数化链接(只要您知道ID))。

这样做的好处是，客户端仅需要知道关系(链接)名称，而服务器几乎可以自由更改关系(和资源)URL。