REST API PATCH或PUT
我想用以下方案的适当方法设计我的休息端点。
有一个组。 每个组都有一个状态。 该组可以由管理员激活或取消激活。
我应该如何设计我的终点？
PUT /groups/api/v1/groups/{group id}/status/activate
要么
PATCH /groups/api/v1/groups/{group id}
with request body like
{action:activate|deactivate}
当您更新现有资源 - 组ID时， PATCH方法是正确的选择。 只有在您完全替换资源时才应使用PUT 。
有关部分资源修改的更多信息，请参阅RFC 5789.具体而言， PUT方法描述如下：
扩展超文本传输协议（HTTP）的几个应用程序需要一个功能来执行部分资源修改。 现有的HTTP PUT方法只允许完整替换文档。 该建议添加了一个新的HTTP方法PATCH来修改现有的HTTP资源。
REST中的R代表资源
（这不是真的，因为它代表具有代表性，但是记住REST中资源的重要性是一个很好的窍门）。
关于PUT /groups/api/v1/groups/{group id}/status/activate ：您没有更新“激活”。 “激活”不是一件事，它是一个动词。 动词永远不是好资源。 经验法则： 如果操作（动词）在URL中，它可能不是RESTful 。
你在做什么呢？ 无论是“添加”，“删除”还是“更新”群组上的激活，或者您更喜欢：操纵群组上的“状态”资源。 就个人而言，我会使用“激活”，因为它们与“状态”概念相比不那么模糊：创建状态不明确，创建激活不是。
POST /groups/{group id}/activation创建（或请求创建）激活。 PATCH /groups/{group id}/activation更新现有激活的一些细节。 由于一个组只有一次激活，我们知道我们所指的是什么激活资源。 PUT /groups/{group id}/activation插入或替换旧的激活。 由于一个组只有一次激活，我们知道我们所指的是什么激活资源。 DELETE /groups/{group id}/activation将取消或删除激活。 当一个集团的“激活”有副作用时，这种模式很有用，例如付款，发送邮件等等。 只有POST和PATCH可能会有这样的副作用。 例如，当激活的删除需要通过邮件通知用户时，DELETE不是正确的选择; 在这种情况下，您可能需要创建一个停用资源： POST /groups/{group_id}/deactivation 。
遵守这些指导原则是一个好主意，因为这个标准合同对于客户以及客户与您之间的所有代理和层次，何时重试安全以及何时不安全都非常明确。 比方说，客户端是一个有wifi的地方，并且它的用户点击“deactive”，这会触发一个DELETE ：如果失败，客户端可以简单地重试，直到它获得一个404,200或其他任何可以处理的东西。 但是如果它触发一个POST to deactivation它不知道重试：POST意味着这一点。
任何客户现在都有一份合同，当遵守合同时，它将防止发送“您的组已被停用”的42封电子邮件，只是因为它的HTTP库不断地重试对后端的呼叫。
更新单个属性：使用PATCH
PATCH /groups/{group id}
如果你想更新属性。 例如，“状态”可以是可以设置的组的属性。 诸如“状态”之类的属性通常是限制值到白名单的好候选者。 示例使用一些未定义的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}
如果您希望替换整个组。 这并不一定意味着服务器实际上创建了一个新组，并且抛出了旧组，例如，ID可能保持不变。 但对于客户来说，这就是PUT的意思：客户应该假设他根据服务器的响应得到一个全新的项目。
如果发生PUT请求，客户端应始终发送整个资源，包含创建新项目所需的所有数据：通常与POST创建所需的数据相同。
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 。
我建议使用PATCH，因为你的资源'组'有很多属性，但在这种情况下，你只更新激活字段（部分修改）
根据RFC5789（https://tools.ietf.org/html/rfc5789）
现有的HTTP PUT方法只允许完整替换文档。 该建议添加了一个新的HTTP方法PATCH来修改现有的HTTP资源。
另外，更详细地说，
PUT和PATCH请求之间的差异反映在服务器处理封闭实体以修改资源的方式中
由Request-URI标识。 在一个PUT请求中，封闭的实体被认为是存储在其上的资源的修改版本
原始服务器，并且客户端正在请求存储的版本
被替换。 然而，对于PATCH，封闭的实体包含一组说明当前驻留在该资源上的资源的说明
应该修改原始服务器以生成新版本。 PATCH方法会影响由Request-URI标识的资源
也可能对其他资源有副作用; 即新的资源
可以创建，或现有的修改，通过应用a
补丁。
根据[RFC2616]第9.1节的定义，PATCH既不安全也不幂等。
客户需要选择何时使用PATCH而不是PUT。 对于
例如，如果补丁文档的大小大于该大小
将在PUT中使用的新资源数据，那么它可能会产生
感觉使用PUT而不是PATCH。 与POST的比较更加困难，因为POST以各种各样的方式使用并且可以
如果服务器选择，则包含PUT和类似PATCH的操作。 如果
该操作不会以可预测的方式修改由Request-URI标识的资源，应考虑POST而不是PATCH
或PUT。
PATCH的响应码是
使用204响应代码是因为响应没有携带消息正文（与200代码的响应会有）。 请注意，其他成功代码也可以使用。
另请参阅thttp：//restcookbook.com/HTTP%20Methods/patch/
警告：实现PATCH的API必须以原子方式修补。 在GET请求时，资源不可能被修补一半。
链接地址: http://www.djcxy.com/p/7097.html