需要帮助了解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]

当用户可以通过PATCH添加或删除用户时,列表的端点list/[id]/add/[id]和list/[id]/remove/[id]端点是多余的还是无用的/list/[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