REST API 最佳实践？返回空对象与无对象答案

【问题标题】：REST API Best practice ? return Empty object vs no objectREST API 最佳实践？返回空对象与无对象
【发布时间】：2021-07-18 23:37:24
【问题描述】：

假设我有一个 API 可以返回用户钱包余额和即将到期的钱包交易列表

response = {
   user_balance: 20
   expiring_credits : [
     {object 1 }
     {object 2}
   ]
}

如果用户没有任何过期交易，我们可以通过 2 种方式格式化 respose 选项 1

 response = {
   user_balance: 20
 }

选项 2

  response = {
    user_balance: 20
    expiring_credits : []
  }

哪个是理想的选择或最佳实践？为什么？寻找一些专家的见解。非常感谢。

【问题讨论】：

标签： javascript node.js api rest backend

【解决方案1】：

您返回的数据应反映所请求数据的形状。如果他们正在询问用户的信息，并且其中包括一对一的用户余额和一对多的到期信用，您应该包括这些关系。如果没有要包含的内容，如果它是一对一的，则专门用 null 调用它，让开发人员知道“这里缺少数据”，如果是一对多，则返回一个空数组，如没有从属记录，但有一个主记录。

一个示例端点：

/user/[id]/credits
GET
id: the user's id
{
  user_balance: null | number, // o:o
  expiring_credits: credits[] // o:m
}

这样，消费开发人员的数据形状始终相同，他们不必担心返回的对象上不存在顶级键。它会一直存在，并且总是与返回的类型保持一致。

如果存在，它将是这种类型。如果它是一个数组，它将永远是一个数组。这让人们可以根据数据形状进行编码，而不是根据数据形状的可能性进行编码。

【讨论】：

【解决方案2】：

保持json响应结构完整总是一个好习惯，这样客户端就不需要了解属性是否为空，因为属性本身由于某些授权而错过了我们，或者可能是因为没有数据存在

如果属性存在而不是数据存在数组，则调用用户删除属性本身将更加清晰。

【讨论】：

【解决方案3】：

哪个是理想的选择或最佳实践？

REST 不在乎。

您在这里遇到的问题是关于架构设计，特别是您的 expiring 信用字段应该是可选的还是必填的。

例如，OpenApi 默认使用可选参数；您的规范必须明确“选择加入”以使用必需参数（“必需”字段是可选的）。这种模式适用于objects in your schema，就像它适用于parameters in your URI 一样（“必需”字段是可选）。

如果您发现需要修改架构，并且希望以不破坏现有客户端的方式进行修改，那么在可选与强制之间的选择可能会影响您以后的工作。 XML community 早前曾探讨过这个问题，因此您需要研究他们的结论（尤其是必须忽略和必须转发等政策）。

【讨论】：

【解决方案4】：

注意：我在这里所说的一切都是基于我自己在 Web 应用程序和 api 开发方面的经验。
根据我的经验，总是向前端或所有其他 API 或 Web 应用程序或任何地方发送静态结构总比不发送它们要好。
我的意思是，如果您正在从事一个项目并且必须将数据发送到下一个实施部门，那么您必须有一个标准来响应您的响应，这意味着您承诺例如您发送一些带有来自 @ 的 200 响应代码的数据987654321@ url，你一定要保证你总是发送["username", "email"] 字段。（即使它们是 null 或空字符串）这使得其他部门（可以是任何部门）始终信任来自您的 api 的响应。

response = {
    user_balance: 20
    expiring_credits : []
  }

这样更好。

【讨论】：

【解决方案5】：

我想不出任何好理由仅仅因为它是空的而忽略一个字段。您也许可以在响应中保存几个字节，但这是一个非常弱的论点。

另一方面：遗漏不等于缺席。 API 可以返回部分响应：

部分响应允许您向应用程序开发人员提供他们需要的信息。

来源：Web API Design: The Missing Link

部分回复：

api.example.com/user/1234默认返回所有字段：

response = {
   user_balance: 20,
   expiring_credits : [
       {object 1 },
       {object 2}
   ]
}

api.example.com/user/1234?fields=user_balance 只发送user_balance，即使存在过期信用也忽略expiring credits：

response = {
   user_balance: 20
}

【讨论】：

【解决方案6】：

更好的做法是发送一个空数组。原因是当有人调用您的 API 并期望 expiring_credits 字段出现在响应中时，如果您因为它是空的而没有发送它，他们可以假设他们发送了错误的请求，因为空数组是一个有效值。

【讨论】：

【解决方案7】：

response = {
  user_balance: 20
  expiring_credits : []
}

选项 2 是最佳做法，原因如下

您不必编写额外的代码来处理 undefined 情况。这只会渲染一个空网格。
不易出现错误。
现在消费者确认 API 提供了正确的响应。只是目前还没有expiring_credits。
在使用 Typescript 等库时，您不必提及可选字段。

【讨论】：