REST API - 在单个请求中批量创建或更新 [关闭]

Question

假设有两个资源Binder 和Doc 具有关联关系，这意味着Doc 和Binder 独立存在。 Doc 可能属于也可能不属于Binder，而Binder 可能为空。

如果我想设计一个允许用户发送Docs 集合的 REST API，IN A SINGLE REQUEST，如下所示：

{
  "docs": [
    {"doc_number": 1, "binder": 1}, 
    {"doc_number": 5, "binder": 8},
    {"doc_number": 6, "binder": 3}
  ]
}

对于docs 中的每个文档，

• 如果存在doc，则将其分配给Binder
• 如果doc 不存在，创建它然后分配它

我真的很困惑应该如何实现：

• 使用什么 HTTP 方法？
• 必须返回什么响应代码？
• 这甚至符合 REST 条件吗？
• URI 看起来如何？ /binders/docs?
• 处理批量请求时，如果一些项目引发错误但其他项目通过怎么办。必须返回什么响应代码？批量操作应该是原子操作吗？

Answer 1

我认为您可以使用 POST 或 PATCH 方法来处理此问题，因为它们通常为此设计。

• 使用POST 方法 通常用于在列表资源上添加元素，但您也可以支持此方法的多个操作。请参阅此答案：Update an entire resource collection in a REST way。您还可以支持输入的不同表示格式（如果它们对应于数组或单个元素）。

  在这种情况下，没有必要定义您的格式来描述更新。

• 使用PATCH 方法 也是合适的，因为相应的请求对应于部分更新。根据 RFC5789 (https://www.rfc-editor.org/rfc/rfc5789)：

  一些扩展超文本传输​​协议 (HTTP) 的应用程序需要一项功能来进行部分资源修改。现有的 HTTP PUT 方法只允许完全替换文档。此提案添加了一个新的 HTTP 方法 PATCH，以修改现有的 HTTP 资源。

  在这种情况下，您必须定义格式来描述部分更新。

我认为在这种情况下，POST 和PATCH 非常相似，因为您实际上不需要描述对每个元素执行的操作。我会说这取决于要发送的表示形式。

PUT 的情况不太清楚。事实上，当使用PUT 方法时，您应该提供整个列表。事实上，请求中提供的表示将替换列表资源之一。

关于资源路径，您可以有两种选择。

• 使用文档列表的资源路径

在这种情况下，您需要在请求中提供的表示中明确地提供带有活页夹的文档链接。

这是此/docs 的示例路线。

这种方法的内容可以是方法POST：

[
    { "doc_number": 1, "binder": 4, (other fields in the case of creation) },
    { "doc_number": 2, "binder": 4, (other fields in the case of creation) },
    { "doc_number": 3, "binder": 5, (other fields in the case of creation) },
    (...)
]

• 使用 binder 元素的子资源路径

此外，您还可以考虑利用子路由来描述文档和活页夹之间的链接。现在不必在请求内容中指定有关文档和活页夹之间关联的提示。

这是此/binder/{binderId}/docs 的示例路线。在这种情况下，如果文档不存在，则使用 POST 或 PATCH 方法发送文档列表将在创建文档后将文档附加到标识符为 binderId 的活页夹。

这种方法的内容可以是方法POST：

[
    { "doc_number": 1, (other fields in the case of creation) },
    { "doc_number": 2, (other fields in the case of creation) },
    { "doc_number": 3, (other fields in the case of creation) },
    (...)
]

关于响应，您可以定义响应级别和要返回的错误。我看到两个级别：状态级别（全局级别）和有效负载级别（更薄的级别）。您还可以定义与您的请求对应的所有插入/更新是否必须是原子的。

• 原子

在这种情况下，您可以利用 HTTP 状态。如果一切顺利，您将获得状态200。如果没有，如果提供的数据不正确（例如 binder id 无效）或其他情况，则返回另一个状态，例如 400。

• 非原子

在这种情况下，将返回状态200，并由响应表示来描述已完成的操作以及最终发生错误的位置。 ElasticSearch 在其 REST API 中有一个用于批量更新的端点。这可能会给你一些关于这个级别的想法：http://www.elasticsearch.org/guide/en/elasticsearch/guide/current/bulk.html。

• 异步

您还可以实现异步处理来处理提供的数据。在这种情况下，HTTP 状态返回将是202。客户端需要拉取额外的资源来查看会发生什么。

在完成之前，我还想注意 OData 规范解决了有关实体之间关系的问题，该功能名为导航链接。也许你可以看看这个;-)

以下链接也可以帮助您：https://templth.wordpress.com/2014/12/15/designing-a-web-api/。

希望对你有帮助 蒂埃里

Answer 2

您可能需要使用 POST 或 PATCH，因为更新和创建多个资源的单个请求不太可能是幂等的。

PATCH /docs 绝对是一个有效的选择。您可能会发现在您的特定场景中使用标准补丁格式很棘手。不确定。

你可以使用 200。你也可以使用207 - Multi Status

这可以通过 RESTful 方式完成。在我看来，关键是拥有一些旨在接受一组文档以更新/创建的资源。

如果您使用 PATCH 方法，我认为您的操作应该是原子的。即我不会使用 207 状态代码，然后在响应正文中报告成功和失败。如果您使用 POST 操作，那么 207 方法是可行的。您必须设计自己的响应主体来传达哪些操作成功，哪些失败。我不知道有标准化的。

Answer 3

PUT ing

PUT /binders/{id}/docs 创建或更新单个文档并将其关联到活页夹

例如：

PUT /binders/1/docs HTTP/1.1
{
  "docNumber" : 1
}

补丁 ing

PATCH /docs 如果文档不存在，则创建它们并将它们与活页夹相关联

例如：

PATCH /docs HTTP/1.1
[
    { "op" : "add", "path" : "/binder/1/docs", "value" : { "doc_number" : 1 } },
    { "op" : "add", "path" : "/binder/8/docs", "value" : { "doc_number" : 8 } },
    { "op" : "add", "path" : "/binder/3/docs", "value" : { "doc_number" : 6 } }
] 

稍后我会提供其他见解，但与此同时，如果您愿意，请查看 RFC 5789、RFC 6902 和 William Durand 的 Please. Don't Patch Like an Idiot 博客条目。

Answer 4

在我工作的一个项目中，我们通过实现我们称为“批处理”请求的东西解决了这个问题。我们定义了一个路径/batch，我们接受以下格式的json：

[  
   {
      path: '/docs',
      method: 'post',
      body: {
         doc_number: 1,
         binder: 1
      }
   },
   {
      path: '/docs',
      method: 'post',
      body: {
         doc_number: 5,
         binder: 8
      }
   },
   {
      path: '/docs',
      method: 'post',
      body: {
         doc_number: 6,
         binder: 3
      }
   },
]

响应的状态码为 207（多状态），如下所示：

[  
   {
      path: '/docs',
      method: 'post',
      body: {
         doc_number: 1,
         binder: 1
      }
      status: 200
   },
   {
      path: '/docs',
      method: 'post',
      body: {
         error: {
            msg: 'A document with doc_number 5 already exists'
            ...
         }
      },
      status: 409
   },
   {
      path: '/docs',
      method: 'post',
      body: {
         doc_number: 6,
         binder: 3
      },
      status: 200
   },
]

您还可以在此结构中添加对标头的支持。我们实现了一些被证明很有用的东西，即在一批请求之间使用的变量，这意味着我们可以将一个请求的响应用作另一个请求的输入。

Facebook 和 Google 有类似的实现：
https://developers.google.com/gmail/api/guides/batch
https://developers.facebook.com/docs/graph-api/making-multiple-requests

当您想使用相同的调用创建或更新资源时，我会根据具体情况使用 POST 或 PUT。如果文档已经存在，是否希望整个文档为：

1. 由您发送的文档替换（即请求中缺少的属性将被删除并覆盖已经存在的属性）？
2. 与您发送的文档合并（即请求中缺少的属性不会被删除，并且已经存在的属性将被覆盖）？

如果您想要备选方案 1 的行为，您应该使用 POST PUT，如果您想要备选方案 2 的行为，您应该使用 PUT PATCH。

http://restcookbook.com/HTTP%20Methods/put-vs-post/