REST API - 批量创建或更新单个请求 [英] REST API - Bulk Create or Update in single request

问题描述

让我们假设有两个资源文件夹和文件与关联关系这意味着文件和文件夹站在自己。 文件可能会或可能不属于文件夹和文件夹可能是空的。

Let's assume there are two resources Binder and Doc with association relationship meaning that the Doc and Binder stand on their own. Doc might or might not belong to Binder and Binder might be empty.

如果我想设计一个REST API，允许用户发送文档的集合 S，在一个请求，像下面

If I want to design a REST API that allows user to send a collection of Docs, IN A SINGLE REQUEST, like the following:

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

和在文档的每个文档，

• 如果在商务部存在，那么它分配给文件夹


• 如果在商务部不存在，创建它，然后将其指定

• If the doc exists then assign it to Binder
• If the doc doesn't exist, create it and then assign it

我以这个应该怎么实现真糊涂。

I am really confused as to how this should be implemented.

• 要使用什么样的HTTP方法？


• 有何反应code必须返回？


• 这甚至对REST资格？


• 将如何URI是什么样子？ /粘合剂/文档？


• 处理批量请求，如果哪几个项目筹集错误，但其他的经历。有何反应code必须返回？如果批量操作是原子？

推荐答案

我认为，你可以使用POST或修补的方法来处理这​​一点，因为它们通常设计这一点。

I think that you could use a POST or PATCH method to handle this since they typically design for this.

• 使用 POST 法通常用于列表资源使用时，添加元素，但你也可以支持采取若干行动此方法。看到这个答案：如何更新REST资源集合。还可以支持不同的重presentation格式的输入（如果它们对应于阵列或单个元素）。

• Using a POST method is typically used to add an element when used on list resource but you can also support several actions for this method. See this answer: How to Update a REST Resource Collection. You can also support different representation formats for the input (if they correspond to an array or a single elements).

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

In the case, it's not necessary to define your format to describe the update.

使用 PATCH 法也是适用的，因为相应的请求对应部分更新。根据RFC5789（ http://tool​​s.ietf.org/html/rfc5789 ）：

延伸的超文本传输​​协议（HTTP）的几个应用要求的特征做局部资源修改。现有的HTTP PUT方法只允许一个完整的替换文件。该提案增加了新的HTTP方法，补丁，修改现有的HTTP资源。

Several applications extending the Hypertext Transfer Protocol (HTTP) require a feature to do partial resource modification. The existing HTTP PUT method only allows a complete replacement of a document. This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource.

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

In the case, you have to define your format to describe the partial update.

我认为在这种情况下， POST 和 PATCH 是非常相似的，因为你并不真正需要介绍操作为每个元素的事情。我会说，这取决于重presentation的格式发送。

I think that in this case, POST and PATCH are quite similar since you don't really need to describe the operation to do for each element. I would say that it depends on the format of the representation to send.

PUT的情况下是有点不太清楚。事实上，使用的方法 PUT 的时候，你应该提供整个列表。作为事实上，在请求中提供重新presentation将在置换列表中的资源之一

The case of PUT is a bit less clear. In fact, when using a method PUT, you should provide the whole list. As a matter of fact, the provided representation in the request will be in replacement of the list resource one.

您可以有关于资源路径有两个选项。

You can have two options regarding the resource paths.

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

• Using the resource path for doc list

在这种情况下，你需要明确地提供文档的链接，与中联重presentation您的要求提供粘合剂。

In this case, you need to explicitely provide the link of docs with a binder in the representation you provide in the request.

下面是本样本路径/文件。

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

The content of such approach could be for method 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) },
    (...)
]

• 使用粘结剂元素的子资源路径


• Using sub resource path of binder element

此外，您还可以考虑利用子路径来描述文档和粘合剂之间的联系。对于一个doc和粘合剂之间的关联的提示不现在已经到请求内容中指定。

In addition you could also consider to leverage sub routes to describe the link between docs and binders. The hints regarding the association between a doc and a binder doesn't have now to be specified within the request content.

下面是本 /粘合剂/ {} binderId /文档样本路线。在这种情况下，发送文档的列表，包括方法 POST 或 PATCH 将附加文档的粘结剂与标识符 binderId`具有创建该文档之后，如果它不存在。

Here is a sample route for this /binder/{binderId}/docs. In this case, sending a list of docs with a methodPOSTorPATCHwill attach docs to the binder with identifierbinderId` after having created the doc if it doesn't exist.

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

The content of such approach could be for method 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) },
    (...)
]

关于响应，这是由你来定义响应并返回错误的水平。我看到两个层次：状态等级（全球范围）和有效载荷级（稀释剂级）。这也是由你来定义是否所有对应您的要求的插入/更新必须是原子或没有。

Regarding the response, it's up to you to define the level of response and the errors to return. I see two levels: the status level (global level) and the payload level (thinner level). It's also up to you to define if all the inserts / updates corresponding to your request must be atomic or not.



• 原子


• Atomic

在这种情况下，您可以利用HTTP状态。如果一切顺利的话，你会得到一个状态 200 。如果没有，像 400 如果提供的数据不正确（如粘合剂ID无效）或别的东西另一个状态。

In this case, you can leverage the HTTP status. If everything goes well, you get a status 200. If not, another status like 400 if the provided data aren't correct (for example binder id not valid) or something else.



• 非原子


• Non atomic

在这种情况下，状态 200 将被退回，这是给重新presentation响应描述做了什么和在哪里错误发生的最终。 ElasticSearch在其REST API进行批量更新的端点。这可以让你在这个级别的一些想法：<一href=\"http://www.elasticsearch.org/guide/en/elasticsearch/guide/current/bulk.html\">http://www.elasticsearch.org/guide/en/elasticsearch/guide/current/bulk.html.

In this case, a status 200 will be returned and it's up to the response representation to describe what was done and where errors eventually occur. ElasticSearch has an endpoint in its REST API for bulk update. This could give you some ideas at this level: http://www.elasticsearch.org/guide/en/elasticsearch/guide/current/bulk.html.



• 异步


• Asynchronous

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

You can also implement an asynchronous processing to handle the provided data. In this case, the HTTP status returns will be 202. The client needs to pull an additional resource to see what happens.

整理之前，我也想注意到的OData规范解决有关与名为导航链接的功能实体之间的关系问题。也许你可以看看这个; - ）

Before finishing, I also would want to notice that the OData specification addresses the issue regarding relations between entities with the feature named navigation links. Perhaps could you have a look at this ;-)

下面这个链接也可以帮助你：<一href=\"https://templth.word$p$pss.com/2014/12/15/designing-a-web-api/\">https://templth.word$p$pss.com/2014/12/15/designing-a-web-api/.

The following link can also help you: https://templth.wordpress.com/2014/12/15/designing-a-web-api/.

希望它可以帮助你，
蒂埃里

Hope it helps you, Thierry

这篇关于REST API - 批量创建或更新单个请求的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！