REST API PATCH或PUT

我想使用适用于以下方案的方法设计我的rest endpoints .

有一个小组 . 每个组都有一个状态 . 管理员可以激活或取消激活该组 .

我应该将我的终点设计为

PUT /groups/api/v1/groups/{group id}/status/activate

要么

PATCH /groups/api/v1/groups/{group id}

with request body like 
{action:activate|deactivate}

回答(5)

2 years ago

当您更新现有资源(组ID)时, PATCH 方法是正确的选择 . 只有在您完全替换资源时才应使用 PUT .

有关部分资源修改的更多信息,请参见RFC 5789 . 具体来说, PUT 方法描述如下:

扩展超文本传输协议(HTTP)的几个应用程序需要一个功能来进行部分资源修改 . 现有的HTTP PUT方法仅允许完全替换文档 . 此提议添加了一个新的HTTP方法PATCH,用于修改现有的HTTP资源 .

2 years ago

REST中的R代表资源

(这不是真的,因为它代表Representational,但它是记住REST在REST中的重要性的好方法) .

关于 PUT /groups/api/v1/groups/{group id}/status/activate :您没有更新"activate" . "activate"不是一个东西,它是一个动词 . 动词永远不是好资源 . 经验法则: if the action, a verb, is in the URL, it probably is not RESTful .

你在做什么呢?您是"adding","removing"或"updating"在组上激活,或者您更喜欢:在组上操作"status" -resource . 就个人而言,我使用"activations"因为它们比概念"status"更不明确:创建状态是模糊的,创建激活不是 .

  • POST /groups/{group id}/activation 创建(或请求创建)激活 .

  • PATCH /groups/{group id}/activation 更新现有激活的一些细节 . 由于一个组只有一个激活,我们知道我们所指的激活资源 .

  • PUT /groups/{group id}/activation 插入或替换旧的激活 . 由于一个组只有一个激活,我们知道我们所指的激活资源 .

  • DELETE /groups/{group id}/activation 将取消或删除激活 .

当组的"activation"具有副作用时,例如正在进行付款,发送邮件等,此模式非常有用 . 只有POST和PATCH可能会产生这样的副作用 . 例如,删除激活需要,比如通过邮件通知用户,DELETE不是正确的选择;在这种情况下,您可能想要创建一个停用资源: POST /groups/{group_id}/deactivation .

遵循这些指导原则是一个好主意,因为这个标准 Contract 使您的客户以及客户端和您之间的所有代理和层,在重试安全时以及何时不安全时非常清楚 . 假设客户端在某个地方有一个片状wifi,并且用户点击"deactive",这会触发 DELETE :如果失败,客户端可以简单地重试,直到它获得404,200或其他任何可以处理的内容 . 但如果它触发 POST to deactivation 它知道不重试:POST意味着这一点 .
任何客户现在都有 Contract ,如果遵循该 Contract ,将防止发送42封电子邮件"your group has been deactivated",原因很简单,因为其HTTP库不断重试对后端的调用 .

更新单个属性:使用PATCH

PATCH /groups/{group id}

如果您想更新属性 . 例如 . “status”可以是可以设置的Groups的属性 . 诸如“状态”之类的属性通常是限制值列入白名单的良好候选者 . 示例使用一些未定义的JSON方案:

PATCH /groups/{group id} { "attributes": { "status": "active" } }
response: 200 OK

PATCH /groups/{group id} { "attributes": { "status": "deleted" } }
response: 406 Not Acceptable

更换资源,没有副作用使用PUT .

PUT /groups/{group id}

如果您希望更换整个集团 . 这并不一定意味着服务器实际上创建了一个新组并抛出旧组,例如ids可能保持不变 . 但对于客户来说,这就是PUT的意思:客户应该假设他根据服务器的响应获得了一个全新的项目 .

PUT 请求的情况下,客户端应始终发送整个资源,包含创建新项目所需的所有数据:通常需要与POST-create相同的数据 .

PUT /groups/{group id} { "attributes": { "status": "active" } }
response: 406 Not Acceptable

PUT /groups/{group id} { "attributes": { "name": .... etc. "status": "active" } }
response: 201 Created or 200 OK, depending on whether we made a new one.

一个非常重要的要求是 PUT 是幂等的:如果在更新组(或更改激活)时需要副作用,则应使用 PATCH . 因此,当更新导致例如发送邮件,请勿使用 PUT .

2 years ago

我建议使用PATCH,因为您的资源“组”有很多属性,但在这种情况下,您只更新激活字段(部分修改)

根据RFC5789(https://tools.ietf.org/html/rfc5789

现有的HTTP PUT方法仅允许完全替换文档 . 此提议添加了一个新的HTTP方法PATCH,用于修改现有的HTTP资源 .

另外,更多细节,

PUT和PATCH请求之间的差异反映在服务器处理随附实体以修改Request-URI标识的资源的方式中 . 在PUT请求中,封闭的实体被认为是存储在源服务器上的资源的修改版本,并且客户端请求替换所存储的版本 . 同然而,PATCH包含一组指令,描述如何修改当前驻留在源服务器上的资源以生成新版本 . PATCH方法影响Request-URI标识的资源,它也可能对其他资源产生副作用;即,可以通过应用PATCH来创建新资源,或者修改现有资源 . PATCH既不是[RFC2616]第9.1节定义的安全也不是幂等的 . 客户端需要选择何时使用PATCH而不是PUT . 例如,如果补丁文档大小大于将在PUT中使用的新资源数据的大小,那么使用PUT而不是PATCH可能是有意义的 . 与POST的比较更加困难,因为POST以各种各样的方式使用,并且如果服务器选择,可以包含PUT和PATCH类操作 . 如果操作未以可预测的方式修改Request-URI标识的资源,则应考虑POST而不是PATCH或PUT .

PATCH的响应代码是

使用204响应代码是因为响应没有携带消息体(具有200代码的响应) . 请注意,也可以使用其他成功代码 .

也请参考http://restcookbook.com/HTTP%20Methods/patch/

警告:实现PATCH的API必须以原子方式进行修补 . 当GET请求时,不可能对资源进行半修补 .

2 years ago

由于您希望使用REST架构样式设计API,因此需要考虑用例来确定哪些概念足以作为资源公开 . 如果您决定将组的状态公开为子资源,您可以为其提供以下URI并实现对GET和PUT方法的支持:

/groups/api/groups/{group id}/status

这种方法相对于PATCH进行修改的缺点是,您无法以原子方式和事务方式对组中的多个属性进行更改 . 如果事务更改很重要,请使用PATCH .

如果您决定将状态公开为组的子资源,则它应该是组表示中的链接 . 例如,如果代理获得组123并接受XML,则响应主体可以包含:

<group id="123">
  <status>Active</status>
  <link rel="/linkrels/groups/status" uri="/groups/api/groups/123/status"/>
  ...
</group>

需要一个超链接来实现REST架构风格的hypermedia as the engine of application state条件 .

2 years ago

我通常更喜欢一些更简单的东西,比如 activate / deactivate 子资源(由 Link Headers 与 rel=service 链接) .

POST /groups/api/v1/groups/{group id}/activate

要么

POST /groups/api/v1/groups/{group id}/deactivate

对于消费者而言,这个界面非常简单,它遵循REST原则,而不会让您将“激活”概念化为单独的资源 .