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模式的最佳实践是什么，其中资源由其他资源拥有，但应该可单独查询？

您所做的是正确的。通常，对于同一资源可以有很多URI-没有规则说您不应该这样做。

通常，您可能需要直接访问项目或作为其他内容的子集访问-因此您的结构对我来说很有意义。

仅仅因为可以在部门下访问员工：

company/{companyid}/department/{departmentid}/employees

并不意味着在公司下也无法访问它们：

company/{companyid}/employees

这将使该公司的员工返回。这取决于您的客户的需求-这就是您应该设计的。

但我希望所有URL处理程序都使用相同的后备代码来满足请求，以免您重复代码。

我尝试了两种设计策略-嵌套和非嵌套端点。我发现：

1. 如果嵌套资源具有主键，而您没有其父主键，则即使系统实际上不需要它，嵌套结构也需要您获取它。

2. 嵌套端点通常需要冗余端点。换句话说，您经常会需要附加的/ employees终结点，这样您就可以获得跨部门的员工列表。如果您有/员工，那么/ companies /部门/员工会怎样购买您？

3. 嵌套端点的发展不尽如人意。例如，您可能不需要现在搜索员工，但是以后可能需要搜索，并且如果您具有嵌套结构，则别无选择，只能添加另一个端点。使用非嵌套设计，您只需添加更多参数即可，这更加简单。

4. 有时，资源可能具有多种类型的父母。结果是多个端点都返回相同的资源。

5. 冗余端点使文档更难编写，并且使api更难学习。

简而言之，非嵌套设计似乎允许更灵活和更简单的端点架构。

我已经将我所做的事情从问题转移到了一个答案上，更多的人可能会看到它。

我所做的是将创建端点放在嵌套端点处，用于修改或查询项目的规范端点不在嵌套资源处。

因此，在此示例中（仅列出更改资源的端点）

• POST /companies/ 创建新公司将返回到创建公司的链接。
• POST /companies/{companyId}/departments 放置部门后，新部门将返回一个链接 /departments/{departmentId}
• PUT /departments/{departmentId} 修改部门
• POST /departments/{deparmentId}/employees 创建新员工返回链接 /employees/{employeeId}

因此，每个集合都有根级别的资源。但是，创建在所有者对象中。

我已经阅读了以上所有答案，但似乎他们没有共同的策略。我从Microsoft Documents找到了一篇有关Design API最佳做法的好文章。我想你应该参考。

在更复杂的系统中，提供一个使客户端能够浏览多个关系级别的URI可能很诱人，例如，/customers/1/orders/99/products.但是，如果将来资源之间的关系发生变化，则这种级别的复杂性可能难以维护，并且不灵活。相反，请尝试使URI保持相对简单。一旦应用程序引用了资源，就应该可以使用该引用来查找与该资源有关的项目。可以将前面的查询替换为URI，/customers/1/orders以查找客户1的所有订单，然后/orders/99/products查找此订单中的产品。

。

小费

避免要求资源URI比复杂 collection/item/collection。

URL的外观与REST无关。什么都可以。它实际上是一个“实现细节”。因此就像您如何命名变量一样。它们所必须的是独特且耐用的。

不要为此浪费太多时间，只需做出选择并坚持下去/保持一致即可。例如，如果您使用层次结构，则将对所有资源进行处理。如果使用查询参数...等，就像代码中的命名约定一样。

为什么这样 ？据我所知，“ RESTful” API是可浏览的（您知道...“作为应用程序状态引擎的超媒体”），因此API客户端不会在乎您的URL是什么，只要它们是有效（没有SEO，没有人需要阅读这些“友好的url”，除了可能用于调试...）

REST API中URL的美观程度/可理解性只是作为API开发人员（而不是API客户端）引起您的兴趣，而不像您代码中的变量名一样。

最重要的是，您的API客户端知道如何解释您的媒体类型。例如，它知道：

• 您的媒体类型具有links属性，其中列出了可用/相关的链接。
• 每个链接都由一种关系标识（就像浏览器知道link [rel =“ stylesheet”]表示其样式表一样，或者rel = favico是指向收藏夹的链接...）
• 并知道这些关系的含义（“公司”表示公司列表，“搜索”表示用于在资源列表上进行搜索的模板化网址，“部门”表示当前资源的部门）

下面是一个HTTP交换示例（由于使用起来更容易，所以它们在yaml中）：

请求

GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml

响应：指向主要资源（公司，人员等）的链接的列表。

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:04:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: this is your API's entrypoint (like a homepage)  
links:
  # could be some random path https://api.acme.local/modskmklmkdsml
  # the only thing the API client cares about is the key (or rel) "companies"
  companies: https://api.acme.local/companies
  people: https://api.acme.local/people

请求：链接到公司（使用以前的响应的body.links.companies）

GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml

响应：公司的部分列表（在项目下），资源包含相关链接，例如用于获取下一对公司的链接（body.links.next）和用于搜索的其他（模板化）链接（body.links.search）

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:06:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: representation of a list of companies
links:
  # link to the next page
  next: https://api.acme.local/companies?page=2
  # templated link for search
  search: https://api.acme.local/companies?query={query} 
# you could provide available actions related to this resource
actions:
  add:
    href: https://api.acme.local/companies
    method: POST
items:
  - name: company1
    links:
      self: https://api.acme.local/companies/8er13eo
      # and here is the link to departments
      # again the client only cares about the key department
      department: https://api.acme.local/companies/8er13eo/departments
  - name: company2
    links:
      self: https://api.acme.local/companies/9r13d4l
      # or could be in some other location ! 
      department: https://api2.acme.local/departments?company=8er13eo

因此，正如您所看到的，如果您使用链接/关系方式，那么构造URL路径部分的方式对您的API客户端没有任何价值。并且，如果您将URL的结构作为文档传达给客户端，那么您就没有使用REST（或者至少不是“ Richardson成熟度模型 ”的Level 3 ）。

我不同意这种路径

GET /companies/{companyId}/departments

如果您想获得部门，我认为最好使用/ departments资源

GET /departments?companyId=123

我想您有一个companies表，departments然后有一个表，然后使用类将它们映射为您使用的编程语言。我还假设部门可以附加到公司以外的其他实体，所以/ departments资源很简单，将资源映射到表很方便，而且由于可以重复使用，因此不需要太多端点

GET /departments?companyId=123

例如任何搜索

GET /departments?name=xxx
GET /departments?companyId=123&name=xxx
etc.

如果要创建部门，则

POST /departments

应该使用资源，并且请求正文应包含公司ID（如果部门只能链接到一个公司）。

Rails为此提供了一种解决方案：浅层嵌套。

我认为这是一个好习惯，因为当您直接处理已知资源时，就无需使用嵌套路由，如此处其他答案所述。