Restful API 命名约定 [关闭]

Question

所以我和我的老板在这里不同意，也找不到任何信息。场景：我想获取某个组织的所有用户。 URL 应该是什么？

mydomain.com/users/by/organisation/{orgId}

或

mydomain.com/organisation/{orgId}/users

我们的论点：

案例 1：调用应该返回“用户”，因此“资源”（调用的第一部分）应该与它相关。

案例 2：组织“拥有”/“是”用户的父级，因此组织应该是第一位的。

你有什么想法？

更新： 我不担心mydomain.com/{resource} 之后会发生什么。问题主要涉及 HTTP 操作（GET、POST、PUT、DELETE）是否应该与第一个资源 mydomain.com/users 相关，或者它是否应该反映关系 mydomain.com/organisations/users/。

Answer 1

让我从这个开始：从技术上讲，这并不重要。 REST 声明 URL 必须可以通过链接发现，就像普通 (HTML) 网页中的链接一样。

但是，一致的、不言自明的 URL 结构根本不会有害。我建议在 URL 中使用层次结构：

• /organisations 返回所有组织的列表
• /organisations/123 返回特定组织 (#123)
• /organisations/123/users 返回与该组织关联的用户列表
• 等

另一种方法是使用查询字符串进行过滤：

• /users 返回所有用户的列表
• /users?organisation=123 返回与该组织关联的用户列表

从这个层次结构的角度来看，/users/by/organisation/123 没有多大意义。调用/users/by/organisation 会有什么结果？还是/users/by？

Answer 2

通过 REST，URI 结构仅从人类的角度来看才重要。从 REST 客户端的角度来看，这无关紧要，因为它遵循带有语义注释的链接。

要回答您的问题，您想描述什么关系或用户很重要。如果要添加和删除关系，则必须定义关系集合。如果要添加和删除用户，则必须定义用户集合。这只有通过操纵才重要。通过 GET，您可以定义任何类型的返回一组用户的查询...

Answer 3

mydomain.com/users/by/organisation/{orgId}

“被”是什么意思？那和任何事情都没有关系。试试keep random words out of the URL。

案例 1：调用应该返回“用户”，因此“资源”（调用的第一部分）应该与它相关。

这不是 RESTful API 强制执行或期望的规则。这在行业中也并不常见，我曾使用过大量的 API。将其视为一个文件夹。

• /users - 用户列表
• /users/1 - ID 为 1 的用户
• /users/1/organizations - 用户所属的组织
• /organizations - 组织列表
• /organizations/1 - 组织编号 1
• /organizations/1/users - 该组织的用户

您像程序员一样看待它，就像它是 SOAP 或 PHP 函数一样，试图创建 getUsersByOrganization($orgId)，但这不是 REST 的工作方式。 :)

如果您必须坚持案例 1（第一个 URI 段 = 返回类型），请执行以下操作：

• /users?orgId=1

这完全是 RESTful，它本质上只是一个过滤器。你甚至可以两者都做，但我不会。这是一种没有立足之地的关系。我尝试将过滤器保留为以下内容：?active=true

Answer 4

您在此处尝试显示的内容之间存在概念差异。第一个是根据一些标准过滤系统中的所有用户资源。第二个是显示属于组织的用户资源。

第二个网址可以显示属于我认为的组织的用户。

第一个 url 有效地过滤了您希望从所有用户中看到的用户。

使用 url 进行过滤可能是可以的，尽管使用 url 查询字符串也可以。所以

mydomain.com/users?organisationId={orgId}

可能更可取。 url 仍然可以包含查询字符串并保持安静。

DELETE mydomain.com/users/organisation/{orgid} 真的有意义吗？你会认为这会删除该组织吗？如果不是，那么这并不是真正指向资源，因此您正在进行搜索，并且可能应该使用查询字符串。

还有其他选项可以进行搜索，例如将搜索条件设为第一类对象，或者使用 this question 或 this question 中的其他过滤技术之一

Answer 5

您可能知道 REST 没有严格的规则，您或多或少可以随意实现它，但这是我的 2 美分

mydomain.com/users/by/organisation/{orgId}

不过，这听起来像是一个不错的 url，因为它可以通过阅读它告诉你它的作用，这不是一个好主意。通常，每个 url 段指定一个存在或可以存在的资源。

在这种情况下，users 代表一个或多个资源，organisation 也代表一个或多个资源，但 by 不代表，这可能只是一个词来帮助澄清 API 的作用。

调用应该返回“用户”，因此“资源”（调用的第一部分）应该与它相关。

资源不一定在 url 的第一部分中指定。如果您愿意，可以是第 2、第 3 或第 10 个

---

mydomain.com/organisation/{orgId}/users

这看起来好多了，但我认为有 1 点改进。您应该将organisation 重命名为organisations，以匹配users

这个

mydomain.com/organisations/{orgId}

然后获取ID为orgId的组织，然后

mydomain.com/organisations/{orgId}/users

获取属于该组织的所有用户。

要进一步缩小范围，您可以这样做

mydomain.com/organisations/{orgId}/users/{userId}

获取属于某个特定组织的特定用户

---

更新：我不担心之后会发生什么 mydomain.com/{resource}。 这个问题主要与 HTTP 操作（GET、POST、PUT、DELETE）应该与第一个相关 resource mydomain.com/users 或是否应反映 关系 mydomain.com/organisations/users/。

回答您的更新：

我在上面已经提到过； 资源不一定在 url 的第一部分中指定。。如果通过将所需资源移到 url 的后面来提高 url 的质量，请继续这样做

Answer 6

第二个更好。沿着 URI 向下走应该会缩小请求的范围，无论是作为过滤器还是显示父子对象。用户属于一个组织，所以它应该是组织/用户。但如果可能的话，我也会摆脱 URI 的“组织”级别。

mydomain.com/{orgId}/users