我想为下面的场景使用适当的方法设计rest端点。
有一群人。每个组都有一个地位。群组可以由管理员激活或灭活。
我应该把终点设计成这样吗
PUT /groups/api/v1/groups/{group id}/status/activate
OR
PATCH /groups/api/v1/groups/{group id}
with request body like
{action:activate|deactivate}
我想为下面的场景使用适当的方法设计rest端点。
有一群人。每个组都有一个地位。群组可以由管理员激活或灭活。
我应该把终点设计成这样吗
PUT /groups/api/v1/groups/{group id}/status/activate
OR
PATCH /groups/api/v1/groups/{group id}
with request body like
{action:activate|deactivate}
当前回答
我通常更喜欢一些简单的东西,比如激活/取消激活子资源(通过rel=service的Link头链接)。
POST /groups/api/v1/groups/{group id}/activate
or
POST /groups/api/v1/groups/{group id}/deactivate
对于消费者来说,这个接口非常简单,并且它遵循REST原则,不会让您陷入将“激活”概念化为单个资源的困境。
其他回答
实现这种行为的一个可能选项是
PUT /groups/api/v1/groups/{group id}/status
{
"Status":"Activated"
}
显然,如果有人需要停用它,PUT将在JSON中具有Deactivated状态。
在需要大规模激活/去激活的情况下,PATCH可以进入游戏(不是针对特定的群体,而是针对群体资源:
PATCH /groups/api/v1/groups
{
{ “op”: “replace”, “path”: “/group1/status”, “value”: “Activated” },
{ “op”: “replace”, “path”: “/group7/status”, “value”: “Activated” },
{ “op”: “replace”, “path”: “/group9/status”, “value”: “Deactivated” }
}
总的来说,这是@Andrew Dobrowolski建议的想法,但在具体实现上略有变化。
由于您希望使用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体系结构样式的应用程序状态条件的引擎。
在这里,PATCH方法是更新现有资源(组ID)的正确选择。只有在替换整个资源时才应该使用PUT。
关于部分资源修改的更多信息可以在RFC 5789中找到。具体来说,PUT方法描述如下:
扩展超文本传输协议的几个应用程序 (HTTP)需要一个特性来做部分资源修改。的 现有的HTTP PUT方法只允许完全替换 文档。此提议添加了一个新的HTTP方法PATCH,用于修改 现有HTTP资源。
我通常更喜欢一些简单的东西,比如激活/取消激活子资源(通过rel=service的Link头链接)。
POST /groups/api/v1/groups/{group id}/activate
or
POST /groups/api/v1/groups/{group id}/deactivate
对于消费者来说,这个接口非常简单,并且它遵循REST原则,不会让您陷入将“激活”概念化为单个资源的困境。
我建议使用PATCH,因为您的资源“组”有许多属性,但在这种情况下,您只更新激活字段(部分修改)
根据RFC5789 (https://www.rfc-editor.org/rfc/rfc5789)
现有的HTTP PUT方法只允许完全替换 一个文档。这个建议添加了一个新的HTTP方法PATCH来修改 现有的HTTP资源。
此外,更详细地说,
The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH. PATCH is neither safe nor idempotent as defined by [RFC2616], Section 9.1.
Clients need to choose when to use PATCH rather than PUT. For example, if the patch document size is larger than the size of the new resource data that would be used in a PUT, then it might make sense to use PUT instead of PATCH. A comparison to POST is even more difficult, because POST is used in widely varying ways and can encompass PUT and PATCH-like operations if the server chooses. If the operation does not modify the resource identified by the Request- URI in a predictable way, POST should be considered instead of PATCH or PUT.
PATCH的响应代码为
使用204响应码是因为响应不携带 消息体(带有200代码的响应将具有此消息体)。请注意 其他成功代码也可以被使用。
也可以参考thttp://restcookbook.com/HTTP%20Methods/patch/
警告:实现PATCH的API必须原子地打补丁。绝对不能 当GET请求资源时,资源可能打了一半补丁。