在创建API时,我喜欢使用正确的HTTP方法。而且通常都很简单。POST用于创建实体,PUT用于更新实体,GET用于检索实体等。
但我在这里有一个用例,其中我将创建一个端点,更新给定1个标识符的多个对象的状态。例如:
/api/v1/entity/update-status
但请注意,我提到了多个对象。我的团队最初的想法是将其映射为POST
,但它实际上不会创建任何东西,而且如果您使用相同的标识符多次调用同一个端点,那么第一次调用后不会发生任何变化。使其幂等。
考虑到这一点,我的想法是将其创建为PUT
甚至PATCH
端点。
你们这些聪明人是怎么想的?
我认为PATCH将是最正确的方式。尽管如果您使用PUT,它也不会是错误的。
PUT和PATCH请求之间的差异反映在服务器处理封闭实体以修改资源的方式由请求URI标识。在PUT请求中,包含的实体被认为是存储在原始服务器,并且客户端请求将存储的版本已更换。但是,对于PATCH,所包含的实体包含一组描述当前驻留在应该修改原始服务器以生成新版本。补丁方法影响由请求URI标识的资源,并且可能对其他资源产生副作用;即,新的资源可能通过PATCH的应用程序创建的或修改的现有的。
虽然在REST API中使用POST
来创建资源是一种约定,但它不一定必须限于此目的。
回到RFC 7231:中POST
的定义
POST方法请求目标资源根据资源自身的特定语义处理请求中包含的表示。例如,POST用于以下功能(以及其他功能(:
- 向数据处理过程提供数据块,例如输入到HTMl表单中的字段
- 向公告板、新闻组、邮件列表、博客或类似的文章组发布消息
- *创建尚未由源服务器识别的新资源;以及*
- 将数据追加到资源的现有表示形式
显然,创建只是其中一个目的,更新现有资源也是合法的。
PUT
操作不适合您的预期操作,因为根据RFC,PUT应该替换目标资源(URL(的内容。这同样适用于PATCH,但由于它用于目标资源的部分更新,因此可以将其定位到集合的URL。
所以我认为你可行的选择是:
POST /api/v1/entity/update-status
PATCH /api/v1/entity
就我个人而言,我会选择PATCH
,因为我觉得它在语义上更令人愉快,但POST
并没有错。在向消费者传达幂等性保证方面,使用PATCH
不会给您带来任何好处。根据RFC 5789:CCD_ 12既不安全也不是幂等的";与CCD_ 13相同。