需要帮助了解 REST API 端点

Question

我不太了解如何合理地构建 REST（或类似 REST）的 API。

想象一个用于创建和发送时事通讯电子邮件的 API。您可能有以下名词/资源：通讯（主题、正文等）、邮件列表（收件人的集合）和收件人（电子邮件地址和相关数据）。

因此您可以使用 PUT 创建资源并返回其 ID：

/newsletter
/list
/user

您可以使用 GET 获取有关资源的信息：

/newsletter/[id]
/list/[id]
/user/[id]

您可以使用 PATCH 更新现有资源（或者这应该是 POST 吗？）：

/newsletter/[id]
/list/[id]
/user/[id]

您可以使用 DELETE 删除资源：

/newsletter/[id]
/list/[id]
/user/[id]

1. 以上正确吗？

2. 哪些端点适用于诸如向列表发送简报、将用户添加到列表等操作？

以下是否有意义，是否为 RESTfull？

/newsletter/[newsletter_id]/send/[mailinglist_id]
/list/[list_id]/add/[user_id]
/list/[list_id]/remove/[user_id]

当可以通过/list/[id] 的 PATCH 添加或删除用户时，为列表设置 list/[id]/add/[id] 和 list/[id]/remove/[id] 端点是多余还是无益？

如何通过电子邮件地址或姓名等属性搜索用户 ID？或者通过名称或创建时间等标识符获取列表？

Answer 1

除了/list/[list_id]/add/[user_id] 和/list/[list_id]/remove[user_id] 之外，您几乎成功了，因为URL 中有动词——这就是HTTP 方法的目的。将它们更改为，例如：

PUT (or POST) to /list/[list_id]/users/ for adding a user to the list

和

DELETE to /list/[list_id]/users/[user_id]

对于搜索，我会使用资源列表的参数化 url，例如：

/newsletter/?name=dfjkhskdfh

Answer 2

这些动词经常被混淆：

1. 要创建实体，请使用 POST
2. 要更新 - PUT

这些东西可以这样处理：

POST /newsletters/[newsletter_id]/mailinglists/[mailinglist_id]/mailingfacts - 执行发送信件，就像在收藏中添加邮寄的事实

/lists/[list_id]/[user_id] - 将用户添加到列表中

/lists/[list_id]/[user_id] - 从列表中删除用户。

Answer 3

当可以通过PATCH/list/[id] 添加或删除用户时，为列表设置list/[id]/add/[id] 和list/[id]/remove/[id] 端点是多余还是无益？

这很糟糕/没有帮助。 REST 的思想之一是端点是资源，而不是远程过程调用 (RPC)。 add 或 remove 建议调用一个过程。

进一步的 GET 请求应该没有副作用，也就是说，它们不进行任何更新。 Further Roy Fielding explains GET as:

检索应该代表某些资源的信息

所以 GET 仅用于检索，而不用于发送数据（即添加/删除哪个用户）。

list/[id]/remove/[id] 的另一个非常危险的问题是，如果蜘蛛或您的测试框架在您的网站上四处游荡，它可能会开始删除项目。