PATCHing集合时的响应体

Question

在REST中，我有一个非常大的集合；它包含数百万项。此集合的路径是/mycollection。

因为这个集合太大了，所以对整个集合进行GET并不是很好的实践，所以API支持分页。分页将是获取集合的主要方式。

GET /mycollection?page=1&page-size=100 HTTP/1.1

假设原始集合包含1,000,000项，我想更新5,000,000项，删除3,000项，并添加2,000项。我可以编写API以支持通过PUT方法或PATCH方法更新集合。虽然这两种方法都需要非常不同的请求机构，但我认为这两种方法都需要完全相同的响应体，即响应体必须包含整个更新资源的当前表示，即集合中的所有999,000项。

正如我前面提到的，GET处理整个集合是不现实的；它太大了。出于同样的原因，我不希望PUTting或PATCHing返回整个集合。向PUT或PATCH请求添加查询参数也不能工作，因为PUT和PATCH都不是安全的方法。

那么，在这个大集合场景中，正确的响应是什么呢？

我可以用

HTTP/1.1 202 Accepted
Location: /mycollection?page=1&page-size=100

202 Accepted响应代码感觉不正确，因为更新是同步进行的。Location头也感觉不太正确。我也许可以使用Links头，但仍然感觉不对。

我再问一次，在这个大集合场景中，正确的反应是什么？

Answer 1

这个问题是基于一种误解：

虽然这两种方法都需要非常不同的请求体，但我相信这两种方法都需要完全相同的响应体，即响应体必须包含整个更新资源的当前表示形式。

可以只返回204 No Content或200 OK，而不返回响应体。没有要求它们在响应中包含完整的表示。

您可以选择支持这一点(可能与Prefer: return=representation头一起支持，也可能支持Content-Location头)，但是如果没有这个标头，我会说返回当前表示形式甚至不是惯例。一般客户端不应该假设响应体是新的表示形式，除非使用了这些标头。

所以，只要返回一个2xx就可以了。

Answer 2

那么，在这个大集合场景中，正确的响应是什么呢？

简短的版本:你应该把一个成功的文章当作一个成功的帖子来对待。

有效载荷的预期含义可以概括为:行为的状态或结果的表示。

所以我们的反应可能很简单

200 OK
Content-Type: text/plain

It worked!

较长的答覆：

虽然这两种方法都需要非常不同的请求体，但我相信这两种方法都需要完全相同的响应体，即响应体必须包含整个更新资源的当前表示形式。

这是不对的--如果您查看RFC 7231，您将看到PUT的响应具有以下描述

对诉讼状态的表述

返回资源的新表示形式是边缘情况，而不是默认情况(请参阅内容定位头的规范)。

对于状态改变的请求，如PUT (4.3.4节)或POST (4.3.3节)，它意味着服务器的响应包含该资源的新表示，从而区别于可能只报告操作的表示(例如，“它成功了！”)。这允许创作应用程序更新其本地副本，而不需要后续的GET请求。

尽管如此，我建议对您选择的方法令牌进行一次审查。PUT和修补程序都支持远程创作语义--要求服务器使其文档副本看起来像本地副本的消息。这就是为什么，例如，放规范在将验证器头字段添加到响应时有很多约束。通用组件可以假设它们知道发生了什么，因为所有的资源都应该以同样的方式理解这些方法。

但是，在您的示例中，不能真正说您是远程创作集合，因为客户端(和通用组件)没有集合的表示，而只是集合的页面的表示。

如果您要与统一界面保持一致，那么您可以

• 允许远程编辑页面，或
• 放弃暗示远程创作的方法标记

当您的请求的语义与标准含义不完全一致时，使用POST是可以的

POST在HTTP中有许多有用的用途，包括“此操作不值得标准化”的一般目的。