api - 需要帮助了解 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]/add/[id] 和 list/[id]/remove/[id] 端点是多余的还是无用的，何时可以通过 /list/[id] 的 PATCH 添加或删除用户？

如何通过电子邮件地址或姓名等属性搜索用户 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