0

我们正在构建一个 API，用于在数据库中插入和更新记录。因此，如果记录基于 Key 存在，则记录将被更新，如果不存在，则将其插入。

我有两个问题。

  • 根据 REST 指南，设计此类 API（例如 PUT/POST 或 PATCH）的选项有哪些？对象列表应该如何表示？注意：我从我读到的其他答案中知道，对于按照 REST 指南应该如何处理存在混淆。所以，如果我能得到一些关于一般最佳实践的指导（不管 REST 部分），我就可以了
  • 其次，我真正困惑的部分是如何表示这个的输出或者这个 API 应该返回什么。

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

4

1 回答 1

0

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

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

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

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

几乎大多数（如果不是所有）API 供应商都为插入实现了这种逻辑。

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

邮政

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

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

放

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

GivenPUT在技术上是一种幂等方法，您既可以忠实于 REST 约定并期望您的用户提供所有属性来更新资源，也可以通过只接受他们想要更新的属性来简化操作。第二个选项不是非常“RESTful”，但从用户的角度来看更容易处理（并减少了有效负载的大小）。

修补

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

该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
      }
  ]
}
于 2019-01-25T10:12:59.253 回答