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没有严格的规则,您或多或少可以自由地实施它,但是这是我的2美分

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

然而,这听起来像一个很好的网址,因为它通过阅读它告诉你它做了什么,这不是一个好主意.通常,每个URL段指定存在或可存在的资源.

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

预期呼叫将返回"用户",因此"资源"(呼叫的第一部分)应与其相关.

资源不一定在网址的第一部分中指定.如果你想要它可以是第2,第3或第10

mydomain.com/organisation/{orgId}/users

这看起来好多了,但我认为有一点改进.您应该重命名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)是否应与第一个 资源 mydomain.com/users相关,或者它是否应该反映mydomain.com/organisations/users/之间的关系.

要回答您的更新:

我已在上面提到过; 资源不一定在网址的第一部分中指定..如果通过将所需资源转移到网址的后面来提高网址的质量,请继续执行此操作

Answer 2

您要在此处展示的内容之间存在概念上的差异.第一种是基于某些标准过滤系统中的所有用户资源.第二个是显示属于组织的用户资源.

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

第一个网址有效地过滤了您想要从所有用户看到的用户.

使用url可能适合过滤,但使用url querystring也可以.所以

mydomain.com/users?organisationId={orgId}

可能更可取.网址仍然可以包含查询字符串并保持安静.

它真的有意义DELETE mydomain.com/users/organisation/{orgid}吗？您希望删除该组织吗？如果没有,那么这并不是真正指向一个资源,所以你正在进行搜索,并且应该使用查询字符串.

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

Answer 3

让我从这开始:从技术上讲,它应该不重要.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？