RESTful API：批量写入操作的最佳路径规范是什么？

Question

想象一下，我们正在围绕一个名为

person

的数据对象设计 API 层

我知道在 RESTful API 中：

“创建人员”调用的路径应如下所示：

PUT https://server-host/persons/<person_id>

“更新人员”调用的路径应如下所示：

UPDATE https://server-host/persons/<person_id>

如果我想进行批量操作，即不创建/更新一个人，而是创建/更新多个人，也许需要一个 ID 列表，该怎么办？

我知道对于批量读取操作，

GET https://server-host/persons

是

GET https://server-host/persons/<person_id>

的替代品。

但这会获取所有人员，除了后端可能内置分页功能，因此每次调用仅返回其中的一些人。如果想要提供 id 列表，也没有关于路径应该是什么的好的建议。

Answer 1

在 RESTful API 设计中，批量操作通常通过创建接受资源列表的端点来处理。以下是处理批量写入操作的方法：

• 批量创建 (POST)：要一次创建多个

  person

  对象，您可以使用

  POST

  方法（不是

  PUT

  ，因为

  PUT

  是幂等的，应该在更新已知对象时使用资源），端点为

  https://server-host/persons

  。请求正文将包含要创建的

  person

  对象数组。

POST https://server-host/persons

[
    {
        "person_id": "1",
        "name": "John Doe",
        ...
    },
    {
        "person_id": "2",
        "name": "Jane Doe",
        ...
    },
    ...
]

• 批量更新（PUT 或 PATCH）：要一次更新多个

  person

  对象，您可以使用具有相同端点

  PUT

  的

  PATCH

  或

  https://server-host/persons

  方法。请求正文将包含一组

  person

  对象及其

  person_id

  和更新的字段。

PUT https://server-host/persons

[
    {
        "person_id": "1",
        "name": "John Smith",
        ...
    },
    {
        "person_id": "2",
        "name": "Jane Smith",
        ...
    },
    ...
]

对于您想要通过 id 获取

person

对象的特定列表的情况，您可以在

GET

请求中将 id 作为查询参数传递：

GET https://server-host/persons?ids=1,2,3,...

服务器将返回具有相应 ID 的

person

对象。此方法假设 id 的数量足够小以符合 URL 长度限制（在某些浏览器中最多可达 2000 个字符）。如果您有大量 id，您可能需要考虑不同的方法，例如使用

POST

请求来检索数据。然而，这不是标准的 RESTful 设计，应谨慎使用。