对 RESTful PUT 端点的客户端的正确响应，用于在单个批次中更新多个实体？

Question

对于更新单个实体（例如文档）的标准 REST PUT 请求，使用如下所示的端点：

[Route("documents/{id}")]
public void Put(int id, [FromBody]Document document)

有一种明确定义的方法可以使用 HTTP 状态代码与客户端通信，使用 HTTP 200 状态表示更新成功，如果未找到具有指定 ID 的文档，则使用 HTTP 404，如果未找到，则使用 HTTP 500更新记录等出现问题

我的问题是我们有一个 RESTful API 的使用率可能非常高。出于性能原因，我们希望创建一个端点，该端点将接受多个文档实体以在单个 PUT 操作中进行更新：

[Route("documents")]
public void Put([FromBody]IEnumerable<Document> documents)

输入如下：

[
    {"Id":1,"Name":"doc one","Author":"Fred"},
    {"Id":2,"Name":"doc two","Author":"John"},
    {"Id":3,"Name":"doc three","Author":"Mary"}
]

如果一个用户提交了10个文档，而我只能成功更新其中的9个，剩下的一个由于某些问题失败了，我想提交9个更新成功的文档，然后与用户沟通哪些更新成功，哪些更新失败。

我可以采用的一种方法是，如果任何提交的文档成功更新，return 一个 HTTP 200。在我 return 给客户端的响应对象中，我可以包含一个列表那些成功的文件和失败的文件列表。对于每一个失败的文档，我都可以包括原因，以及每个失败文档的 HTTP 状态代码。

但是，如果某些请求失败，我应该 return 发送 HTTP 200 吗？这种方法依赖于客户端检查失败文档列表以查看是否存在问题。我担心用户会看到 HTTP 200 并认为一切正常。

另一种选择是，如果客户端提交了 10 个文档，而我能够成功更新其中的 9 个，但一个失败了，return 失败的那个的 HTTP 状态代码。例如，如果因为找不到指定的 ID 而失败，return HTTP 404，如果因为数据库不可用而失败，return HTTP 500，等等。

这种方法也有问题。例如，如果两个文档由于不同的原因而失败，应该 returned 哪个 HTTP 状态代码？ return 是否有意义，例如，成功更新某些项目的请求的 HTTP 500 状态？

REST指南对本次批量更新有什么建议吗？对于这个问题有什么推荐的方法吗？

Answer 1

HTTP Status 207 Multi Status 可用于处理批处理。

当处理多个实体时，您的 API 可以 return 包含响应列表的 207 状态响应：

每个实体和响应共享一个密钥，允许消费者知道哪个响应对应于哪个提供的实体。在提供的用例中，文档的 Id 可以用作键。
每个响应都包含您在单独处理相应实体时收到的相同数据（包括 http 状态）。

RFC 指出消息在 XML 中，但您可以将 JSON 与您自己的结构一起使用。您可以查看处理 batch processing 的 Jive API 以查看示例。

给定输入

[
  {"Id":1,"Name":"doc one","Author":"Fred"},
  {"Id":2,"Name":"doc two","Author":"John"},
  {"Id":3,"Name":"doc three","Author":"Mary"}
]

完全成功会 return 一个 207 http 状态，响应包含三个 200 http 状态：

[
  {
    "Id": 1,
    "status": 200,
    "data" : { data returned for a single processing }
  },
  {
    "Id": 2,
    "status": 200,
    "data" : { data returned for a single processing }
  },
  {
    "Id": 3,
    "status": 200,
    "data" : { data returned for a single processing }
  }
]

如果 ID 为 3 的实体出现问题，例如缺少作者：

[
  {"Id":1,"Name":"doc one","Author":"Fred"},
  {"Id":2,"Name":"doc two","Author":"John"},
  {"Id":3,"Name":"doc three"}
]

响应仍将是 207，但将包含 ID 1 和 2 的两个 200 http 状态和 ID 3 的 400 状态。

[
  {
    "Id": 1,
    "status": 200,
    "data" : { data returned for a single processing }
  },
  {
    "Id": 2,
    "status": 200,
    "data" : { data returned for a single processing }
  },
  {
    "Id": 3,
    "status": 400,
    "data" : { data returned for a single processing 400 error }
  }
]

对 RESTful PUT 端点的客户端的正确响应，用于在单个批次中更新多个实体？

Proper response to client for a RESTful PUT endpoint for updating multiple entities in a single batch?

rest

api-design

restful-architecture

asp.net-web-api