RESTful api 和相关资源

Question

我正在开发我的第一个 RESTful api，（不幸的是）这是在一个已经存在的系统上完成的，这个想法是允许第三方访问这个系统。

一切都很好，直到我意识到我有多种方法可以访问相同的资源。我将尝试使用系统的一部分来解释它。该系统是使用 Laravel 5.8 构建的，其中包括以下数据库表：

• 用户
• 电子邮件
• 短信

每个用户可以拥有多封电子邮件，每封电子邮件只属于一个用户。这同样适用于文本消息。

我已经“忽略”了当前的所有代码，因为它没有以正确的方式构建以使其成为 RESTful api，所以我创建了一个新文件夹Api，我的所有代码都在那里。

我认为有以下端点是有意义的

/api/v1/users
/api/v1/users/1
/api/v1/users/1/emails
/api/v1/users/1/emails/1
/api/v1/users/1/sms
/api/v1/users/1/sms/1

通过这种方式，我可以获得用户列表、获取用户的所有详细信息、获取电子邮件/短信列表以及特定电子邮件/短信的所有详细信息。但是，其中一项要求是拥有一个包含电子邮件/短信列表的页面，因此拥有以下内容开始变得有意义：

/api/v1/emails
/api/v1/emails/1
/api/v1/sms
/api/v1/sms/1

为了避免有 2 个端点来获取相同的资源（/api/v1/users/1/emails/1并/api/v1/emails/1返回 ID 为 1 的电子邮件），我正在考虑摆脱深层端点/api/v1/users/1/emails并将它们更改为类似/api/v1/emails?user_id=1.

这是否违反了 RESTful 原则？我无法就让 2 个端点访问同一资源的研究得出结论，但“感觉”不对。另一方面， have/api/v1/emails?user_id=1可能会引起一些安全/隐私问题（例如，我需要确保用户 1 只能访问/api/v1/emails?user_id=1而不能访问/api/v1/emails?user_id=2），但似乎更灵活，因为我可以单独使用它来获取所有资源或与user_id 过滤器以仅获取特定资源。

这种情况有约定吗？

Answer 1

回顾一下我们如何理解 REST 上下文中的“资源”可能会有所帮助。

任何可以命名的信息都可以是资源：文档或图像、临时服务（例如“洛杉矶今天的天气”）、其他资源的集合、非虚拟对象（例如人）等等。换句话说，任何可能成为作者超文本参考目标的概念都必须符合资源的定义。

/api/v1/users/1/emails
/api/v1/emails?user_id=1
/66eb6757-254e-49b4-bc8a-d04330f4482e

REST 将标识符视为语义上不透明的——通用客户端不使用标识符的拼写来理解正在发生的情况。考虑一个网络浏览器 - 它知道这http://example.org/cat.jpg是一个图像，不是因为jpg，而是因为img。

这意味着服务器可以使用它喜欢的任何拼写——编码到 URI 本身中的任何信息都是由服务器自行决定并供其自己使用。

这并不是说使用“可猜测”的拼写没有任何优势；而是说，使用“可猜测”的拼写没有任何优势。只是 REST 完全不知道标识符是否应该是可猜测的。

为标识符选择拼写以使您的实现更简单是完全在范围内的。