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中获益较少）。

嵌套的方法真的比平面更好吗，超越美学，从而证明为支持资源URL构建中缺乏统一性而引入的额外努力和复杂性是合理的？

从一些评论和回答中，我意识到我在一个方面不够清楚：我并不反对使用/employees/5或/departments/1这样的URL对单个资源进行寻址。我不认为那是嵌套的。

当我说嵌套资源时，我指的是类似/departments/1/employees这样的URL，其中一个资源总是在另一个资源的上下文中寻址。主要的问题是，对于URL构建，泛型库需要知道一些额外的东西，比如“员工嵌套在部门下”，但“分支机构不嵌套在任何东西下”。如果所有的资源都可以用RESTFLILY方式处理，但以平面方式处理，那么知道如何处理它们就会更简单、更可预测。

考虑一下，在数据库中，您不需要知道额外的信息就可以知道如何处理对象集合（例如RDMS中的表）。您总是将员工集合引用为employees，而不是departments/5/employees。

Answer 1

如果你想再往下钻几层，会发生什么呢？

/API/地址？DepartmentId=1&EmployeeId=2&AddressId=3

VS

地址endpoint突然因为参数而变得臃肿。

此外，如果您正在研究Richardson成熟度模型level 3，那么RESTful API应该是可以通过链接发现的。例如，在顶层，例如/api/version(/1)，您会发现有一个指向部门的链接。下面是在HAL Browser这样的工具中的情况：

"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）。