Question

我们正在构建一个API，该API将用于插入和更新数据库中的记录。因此，如果记录基于密钥存在，那么记录将被更新，如果不存在，那么它将被插入。

我有两个问题。

根据REST指南，设计此类API的选项有哪些，例如放置/张贴或修补？对象列表应如何表示？注意：我从其他答案中知道，我读到按照REST准则应该如何处理存在困惑。因此，如果可以从通用最佳实践中获得一些指导（与REST部分无关），我可以。
第二，我真正困惑的部分是如何表示此输出或该API应该返回什么。

对于上述主题的具体指导/意见，我们将不胜感激。

Answer 1

我已经看到各种供应商（Stripe，HubSpot，PayPal，Google，Microsoft）的插入/更新有许多不同的实现。尽管它们有所不同，但这种差异在某种程度上与它们的总体API实现完全吻合，通常不会造成压力。

话虽如此，插入的“一般”规则是：

POST /customers-在body中提供客户详细信息。

这将创建一个新客户，并在响应中返回唯一ID和客户详细信息（以及createdDate和其他自动生成的属性）。

如果不是所有的API供应商，绝大多数情况下，都会为插入实现此逻辑。

更新是完全不同的。您的选择包括：

POST

POST /customer/<customer_id>-在正文中包含要更新的属性和值。

您在这里使用POST更新客户。这不是一个很常见的实现，但是我已经在几个地方看到过它。

放置

PUT/customer/<customer_id>-在正文中包含全部或部分更新的属性。

考虑到PUT从技术上讲是幂等的方法，您可以遵循REST约定并期望您的用户提供所有属性来更新资源，或者通过仅接受他们想要的属性来使其变得更简单更新。第二个选项不是很“ RESTful”，但是从用户角度来看更易于处理（并减小了有效负载的大小）。

PATCH

PATCH /customer/<customer_id>-在正文中包含您要更新/删除/替换/等的操作和属性。有关如何PATCH的更多信息。

PATCH方法用于部分更新，这就是您“想要”调用部分更新的方式。从消费者的角度来看，使用起来有点困难。

现在，这就是偏见的所在。我个人更喜欢使用POST，在这里我不需要提供所有属性来调用更新（只是我要更新的属性）。原因是由于使用简单。

就更新的响应主体而言，通常它们将在响应主体内返回的对象包括更新的属性（以及更新的自动生成的属性，例如updatedDate）。

批量插入/更新

查看Facebook Graph HTTP API (Batch Request)的灵感，并假设POST是更新的首选方法，则可以使用专用的batch资源作为选项嵌入一系列请求。

端点：POST /batch/customers

身体：

{
   ["first_name": "John", "last_name": "Smith"...], //CREATE
   ["id": "777", "first_name": "Jane", "last_name": "Doe"...], //UPDATE
   ["id": "999", "first_name": "Mike", "last_name": "Smith"...], //UPDATE
   [....]
}

示例响应

{
  "id": "123",
  "result":[
      { // Creation successful
        "code": 200,
        "headers":{..},
        "body": {..},
        "uri": "/customers/345"
      },
      { // Update successful
        "code": 200,
        "headers":{..},
        "body": {..},
        "uri": "/customers/777",
      },
      { // A failed update request
        "code": 404,
        "headers":{..},
        "body": {..}, // body includes error details
      }
  ]
}

如果将REST API用于插入/更新记录列表，那么设计REST API的标准做法是什么？

1 个答案: