是否可以将REST资源嵌套在“目录”中，以指示资源属于类似类型，而不是指示属于某个层次结构？

Question

将资源嵌套在RESTful API中很常见。例如，要检索ID = 5的公司中的员工：

GET /companies/5/employees

在REST设计中，将资源放在一个不属于公共父资源实例的公共“目录”中是否也普遍可以接受？这更像是一种“is-a”关系，我认为典型的嵌套结构具有“属于”关系中的嵌套资源。

例如，将以下两种不同的资源（内部代理，外部代理）分组是否可以接受？在这种情况下，路径的agents部分是描述其后代但不是父资源的类别。

GET /agents/internal
GET /agents/external

没有计划使用/agents路径添加任何资源;它仅用于分组目的。

或者这样的事情要避免吗？

GET /internal-agents
GET /external-agents

我觉得第二个选项更正确，但我喜欢的第一个选项是美学。

Answer 1

鉴于您有一些agents可以是internal或external：

• / agents / internal打破网址一致性是一个糟糕的主意
• / internal-agents是一个有效的想法，但要注意缺点
• 对于此用例，过滤器可能更好：GET / agents？status = internal

/ agents / internal打破网址一致性是个坏主意

拥有/ agents / internal是一个糟糕的想法，它不能被使用，因为它会导致你的API中不一致的URL，人类和程序都不会轻易理解。

• REST URL的最佳模式（排除域和版本控制问题）就是这一点：/resources/{resouce id}/sub-resources/{sub-resource id}/ /不应超过2个级别。 您的第一个示例/companies/5/employees就是一个很好的例子。
• 添加/agents/internal网址会使您的API网址不一致且难以理解为人类以及程序。您可以结束GET /agents/2，其返回ID为2的代理以及返回内部代理列表的GET /agents/internal。相同的网址结构，但意义不同。

使用一致的URL结构有助于理解语义，甚至不知道API的作用。

/ internal-agents是一个有效的想法，但要注意缺点

您有两个特定资源internal-agents和external-agents的想法是有效的。 但它可能有一些缺点，具体取决于确切的用例：

• 如果您添加更多状态，例如partner，则必须添加新资源partner-agents
• 如果消费者想要检索这两种类型，则必须进行调用，或者您必须创建/agents资源

过滤器可能更适合此用例：GET / agents？status = internal

第三个想法是将内部和外部视为对/agents资源上某些状态的过滤。

• GET /agents返回所有座席（内部+外部）
• GET /agents/2返回ID为2的代理
• GET /agents?status=internal返回内部状态
的座席
• GET /agents?status=external返回具有外部状态的代理

如果您添加新状态，例如partner：

• GET /agents返回所有座席（内部+外部+新合作伙伴状态）
• GET /agents/2仍会返回ID为
的座席
• GET /agents?status=internal仍会返回具有内部状态的代理
• GET /agents?status=external仍会返回具有外部状态的代理
• GET /agents?status=partner返回具有新合作伙伴身份的代理
• GET /agents?status=internal,partner返回具有内部或合作伙伴身份的代理

在过滤器和特定资源之间进行选择只是一个上下文。 唯一要记住的是确保URL的一致性。