REST嵌套资源的最佳实践是什么？

Question

REST嵌套资源的最佳实践是什么？

据我所知，每个资源应该只有一个规范路径。因此，在下面的示例中，优秀的URL模式是什么？

以公司的休息代表为例。在这个假设的例子中，每个公司拥有 0个或更多部门，每个部门拥有 0个或更多员工。

没有关联公司，部门就不可能存在。

没有相关部门，员工就不能存在。

现在我会找到资源模式的自然表示。

• /companies 一系列公司 - 接受新公司的接受。获取整个系列。

• /companies/{companyId}一家公司。接受GET，PUT和DELETE

• /companies/{companyId}/departments接受新项目的POST。（在公司内部创建一个部门。）

• /companies/{companyId}/departments/{departmentId}/

• /companies/{companyId}/departments/{departmentId}/employees

• /companies/{companyId}/departments/{departmentId}/employees/{empId}

考虑到约束，在每个部分中，我觉得如果有点深度嵌套，这是有道理的。

但是，如果我想列出（GET）所有公司的所有员工，我的困难就来了。

最合适的资源模式将映射到/employees（所有员工的集合）

这是否意味着我应该/employees/{empId}也是因为如果是这样，那么有两个URI可以获得相同的资源？

或者整个架构可能会被夷为平地，但这意味着员工是一个嵌套的顶级对象。

在基本级别，/employees/?company={companyId}&department={deptId}返回与最深层嵌套模式完全相同的员工视图。

URL模式的最佳实践是什么，其中资源由其他资源拥有但应该可以单独查询？

---

更新：请参阅下面的答案，看看我做了什么。

Answer 1

你所做的是正确的。通常，同一资源可能有许多URI - 没有规则表明您不应该这样做。通常，您可能需要直接访问项目或作为其他内容的子集 - 因此您的结构对我来说很有意义。仅仅因为员工可以在部门下访问：company/{companyid}/department/{departmentid}/employees并不意味着他们也无法在公司下访问：company/{companyid}/employees哪个会让该公司的员工回归。这取决于您的消费客户需要什么 - 这就是您应该设计的内容。但我希望所有URL处理程序使用相同的支持代码来满足请求，这样您就不会复制代码。

Answer 2

我尝试了两种设计策略 - 嵌套和非嵌套端点。我发现：如果嵌套资源具有主键并且您没有其主键，则嵌套结构要求您获取它，即使系统实际上并不需要它。嵌套端点通常需要冗余端点。换句话说，您通常需要额外的/员工端点，以便获得跨部门的员工列表。如果您有/员工，/公司/部门/员工到底会给您带来什么？嵌套端点不会很好地发展。例如，您现在可能不需要搜索员工，但您可能稍后会进行搜索，如果您有嵌套结构，则别无选择，只能添加另一个端点。使用非嵌套设计，您只需添加更多参数，这更简单。有时资源可能有多种类型的父母。导致多个端点都返回相同的资源。冗余端点使得文档更难编写，也使得api更难学习。简而言之，非嵌套设计似乎允许更灵活和更简单的端点模式。

Answer 3

我把我从问题所做的事情转移到了更多人可能会看到它的答案。我所做的是在嵌套端点上创建创建端点，修改或查询项目的规范端点不在嵌套资源上。所以在这个例子中（只列出更改资源的端点）POST /companies/ 创建新公司返回创建公司的链接。POST /companies/{companyId}/departments 当一个部门被放置创建新部门返回一个链接 /departments/{departmentId}PUT /departments/{departmentId} 修改一个部门POST /departments/{deparmentId}/employees 创建一个新员工返回一个链接 /employees/{employeeId}因此，每个集合都有根级资源。然而，创建是在拥有对象中。