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

Question

假设我有一个 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 : []
  }

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

Answer 1

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

一个示例端点：

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

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

如果它存在，它将是这种类型。如果它是一个数组，它将始终是一个数组。这让人们编码到数据形状，而不是数据形状的可能性。

Answer 2

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

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

Answer 3

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

REST 不在乎。

您在这里遇到的是关于架构设计的问题，特别是您的expiringcredits 字段是否应该是可选的或强制性的。

例如，OpenApi 默认使用可选参数；您的规范必须明确“选择加入”使用必需参数（“必需”字段是可选的）。此模式适用于架构中的对象，就像它适用于 URI中的参数一样（“必填”字段是可选的）。

如果您发现需要修改架构，并且希望以不破坏现有客户端的方式进行修改，则在可选与强制之间的选择可能会影响您以后的工作。该XML社区探索的一天，这个问题后面，所以你会想看看他们的结论（以及像特别政策必须-忽视和必须向前）。

Answer 4

我想不出有什么好的理由仅仅因为它是空的而省略一个字段。您可能能够在响应中保存几个字节，但这是一个非常弱的论点。

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

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

来源：Web API 设计：缺失的链接

部分响应：

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
}

Answer 5

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

Answer 6

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

response = {
    user_balance: 20
    expiring_credits : []
  }

所以这样更好。