按id或类型和语言更新资源的RESTful约定

Question

目前，按类型和语言划分的GET请求只能返回一个文档：

GET /documents?type=invitation&language=en

id: 50
text: "I would like to invite..."

更新资源的正确restful约定是什么？

PUT /documents?type=invitation&language=en

?？或者我应该只使用id更新资源？

PUT /documents/50

Answer 1

在更新整个资源时通常使用PUT。在这里，您只是发送资源数据的子集-所以您应该使用修补程序。

您的URL应该是：

PATCH /documents/{id}

然后，在请求有效负载中获得要更新的所有数据：

{
   "type": "invitation",
   "language": "en"
}

因此，现在每个请求只更新一个对象，并使用适当的方法和资源表示法。

Answer 2

更新资源的正确restful约定是什么？

通常，您希望使用相同的URI请求对用于检索其副本的资源进行更改。

这样做的动机是缓存- HTTP内置了无效缓存响应的规则。它不是一种通用机制，而是设计用来处理一些非常特殊的情况(仅基于目标URI、位置字段和内容位置字段的无效响应)。

因此

GET /your-resource-identifier-here

建议编辑应该通过

POST /your-resource-identifier-here
PUT /your-resource-identifier-here
PATCH /your-resource-identifier-here

PUT /documents?type=invitation&language=en

对于发送资源替换表示的请求(如“保存文件”)，这是一个完全正常的选择。

如果您打算请求只修改文档的一部分，可以考虑发送一个补丁文档作为请求体，并使用HTTP方法修补程序。

如果表示为JSON，那么修改文本的请求可能如下所示：

PATCH /documents?type=invitation&language=en
Content-Type: application/json-patch+json

[{
 "op": "replace",
 "path": "text",
 "value": "your new text here"
}]

Answer 3

这取决于/documents?type=invitation&language=en的回报。如果这是某种类型的搜索，并且您希望稍后会有多个文档，那么PUT应该更新所有这些文档，而且由于它是一个完整的更新而不是一个部分，所以它没有多大意义。在这种情况下使用PATCH更好，因为它甚至可以对多个资源进行部分更新。如果这个URI是这个单一资源的唯一标识符，那么您可以使用它而不是/documents/50或与它一起使用它。对于同一资源，可以有多个标识符。