api - 在 REST Api 调用中批量更新集合的最佳实践

<分区>

您好，我正在寻找 API 设计的最佳实践，以通过 API 调用批量更新集合。

我的收藏有 URL/api/v1/cars，我想更新收藏中的所有汽车以添加当前时间的时间戳。

{
    data: [
    {
        manufacturer: 'Porsche',
        timestamp: ...
    },
    {
        manufacturer: 'BMW',
        timestamp: ...
    }
    {
        manufacturer: 'Peugeot',
        timestamp: ...
    }
}

我考虑了几个选项，但我想不出什么是最佳做法。

应该是:

1/建模为另一个资源，例如 POST api/v1/cars/updateTimestamp

2/作为查询参数传递:PUT api/v1/cars?updateTimestamp

3/传入请求正文:

POST api/v1/cars 
{"operation":"Update timestamps"}

我想强调的是，整个处理应该在后端完成，而不是由客户端传递。对于后端发生的任何复杂处理，都会发生同样的问题。在这种情况下，我如何才能保留 API RESTy。

非常感谢您的帮助/任何指向相关资源的指针。

最佳答案

由于在 HTTP 中没有定义部分 PUT，您需要为每个资源发送整个实体以进行更新或使用一些其他操作。

发布

由于 POST 是一个通用操作，您可以使用它在服务器上创建一个短暂的临时资源(甚至不需要 own URL )。收到后，服务器可以使用某些提供的字段值组合更新所有指定的条目或一般的所有条目(尽管如果该列在关系数据库中尚不为人所知，则可能需要更改某些表)

一个简单的请求可能是这样的:

POST /api/v1/cars/addAttributes HTTP/1.1
Host: example.org
Content-Length: 24
Content-Type: application/json
If-Match: "abc123"

{
  "timestamp": "..."
}

这种方法的优点是它可以随时发送到服务器，即使事先不知道当前状态。然而，这也有某些条目被更新的危险，这些条目不应该受到影响。这可以通过指定 If-Match header 来影响，该 header 指向特定的版本哈希并在每次实体更新时更改，或者通过向 JSON 主体添加特定的限制器，服务器也必须明白。

补丁

类似于POST，可以向服务器发送任何内容，PATCH 用于修改资源。单个请求可能会同时更新多个资源，但是，客户端需要定义将资源从状态 A 转换为状态 B 的必要步骤。因此，客户端还需要拥有资源的最新状态才能成功将资源转换为其最新状态(-> ETag 和 If-Modified HTTP header )

A JSON Patch因此，对所提供示例的请求可能如下所示:

PATCH /api/v1/cars HTTP/1.1
Host: example.org
Content-Length: 215
Content-Type: application/json-patch+json
If-Match: "abc123"

[
  { "op": "add", "path": "/data/1", "value": [ "timestamp", "..." ] },
  { "op": "add", "path": "/data/2", "value": [ "timestamp", "..." ] },
  { "op": "add", "path": "/data/3", "value": [ "timestamp", "..." ] }
]

其中/data/1、/data/2和/data/3是资源的唯一标识保时捷、宝马和标致。

PATCH 指定请求必须是原子的，这意味着要么所有指令成功，要么全部不成功，这也为表带来了一些事务要求。