我们正在构建一个API，用于在数据库中插入和更新记录。因此，如果记录基于键存在，则记录将被更新，如果没有，则将插入记录。
我有两个问题。
- 根据 REST 指南，设计此类 API 的选项是什么，例如 PUT/POST 或补丁？对象列表应如何表示？ 注意：我从我读到的其他答案中知道，根据 REST 指南应该如何存在混淆。所以如果我能得到一些关于一般最佳实践的指导(无论 REST 部分如何)，我就可以了
- 其次，我真正困惑的部分是如何表示这个的输出或这个 API 应该返回什么。
如能就上述主题提供具体指导/投入，将不胜感激。
我已经看到了不同供应商(Stripe，HubSpot，PayPal，Google，Microsoft)的插入/更新的许多不同的实现。尽管它们不同，但这种差异在某种程度上与它们的整体 API 实现非常吻合，通常不会造成压力。
话虽如此，插入的"一般"规则是：
POST /customers- 在body内提供客户详细信息。
这将创建一个新客户，在响应中返回唯一 ID 和客户详细信息(以及createdDate和其他自动生成的属性)。
几乎大多数(如果不是全部)API 供应商都为插入实现此逻辑。
更新，是完全不同的。您的选项包括：
发布
POST /customer/<customer_id>- 包括要在正文中更新的属性和值。
在这里，您可以使用POST来更新客户。这不是一个很常见的实现，但我在几个地方看到过它。
放
PUT/customer/<customer_id>- 在正文中包含所有或部分更新的属性。
鉴于PUT在技术上是一种幂等方法，您可以保持 REST 约定并期望用户提供所有属性来更新资源，或者通过仅接受他们想要更新的属性来简化它。第二个选项不是很"RESTful"，但从用户的角度来看更容易处理(并减小有效负载的大小)。
补丁
PATCH /customer/<customer_id>- 在正文中包含要更新/删除/替换/等的操作和属性。更多关于如何打补丁的信息。
PATCH方法用于部分更新，这就是调用部分更新的"含义"。从消费者的角度来看，使用起来有点困难。
现在，这就是偏见开始的地方。我个人更喜欢使用POST，其中我不需要提供调用更新的所有属性(只是我想更新的属性)。原因是由于使用简单。
就更新的响应正文而言，通常它们会在响应正文中返回的对象包括更新的属性(以及更新的自动生成的属性，例如updatedDate)。
批量插入/更新
查看Facebook Graph HTTP API(批处理请求)以获取灵感，并假设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
}
]
}