Restful API 命名约定 [关闭]

Posted 2023-02-23

【中文标题】Restful API 命名约定 [关闭]

【英文标题】：Restful API naming conventions [closed]

【发布时间】：2014-07-25 03:04:13

【问题描述】：

所以我和我的老板在这里不同意，也找不到任何信息。场景：我想获取某个组织的所有用户。 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/。

【问题讨论】：

一个用户可以是两个组织的成员吗？

@SamHolder 是的，有一个链接表

Example #2 对我来说是正确的，它看起来更像 REST，而 URL 中的“by”感觉是多余的。

相关：***.com/questions/778203/…

【参考方案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？

【参考方案2】：

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

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

【讨论】：

对不起，如果重复，但在上面找不到任何东西......

最近两天的类似问题：***.com/questions/23957974/…***.com/questions/24011490/…***.com/questions/24001825/…

我可以询问您所做的许多编辑，这些编辑完全修改了答案吗？

我更正了关于 REST 的旧答案。我是在阅读该主题的科学文章之前写的，所以大多数都是完全错误的。

顺便说一句。我有大约 70 个要走（每天允许 10 个）。我应该停止这个吗？

【参考方案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

【参考方案4】：

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

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

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

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

mydomain.com/users?organisationId=orgId

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

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

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

【讨论】：

这对我来说很有意义，HTTP 操作 = 删除，我要删除什么 = 组织 = id 的用户。

那么DELETE mydomain.com/organisation/orgId/users 会删除包含该用户的用户或组织吗？

【参考方案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 的质量，请继续这样做

【讨论】：

如果是mydomain.com/users/organisation/orgId？我不太关心/user 或/organisations 之后发生的事情，我的问题是是否遵循父子关系或与资源的关系

@We0 我刚刚编辑了这个：资源不一定在 url 的第一部分中指定。。所以在那种情况下是的，你想做父母/孩子/孩子

@We0 我做了一个新的编辑来回答你的更新

好的，谢谢，有道理

完全同意！！

【参考方案6】：

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

mydomain.com/orgId/users

【讨论】：

我不能放弃组织部分，因为我们有 /users、/orders 等，但谢谢

我这样问你，如果我想删除一个组织的所有用户，你会推荐DELETE /organisations/orgId/users吗？不知何故，我认为 HTTP 操作（PUT、POST、DELETE、GET）应该与资源相关......

是的。动词是你对资源所做的事情。你GET/organisations/orgId/users 的所有用户列表，所以如果你想DELETE 所有用户，你使用相同的地址。两个地址都访问相同的资源，但动词指定了你对该资源做什么。

是的，但我不是“获取”或“删除”组织，我是“获取”用户？

您正在获取或删除属于该组织的用户