REST - 部分资源

Question

在REST设计中，允许返回部分资源是很常见的。在这种情况下，我想允许用户仅指定要在该资源的JSON表示中返回的某些字段。

例如，假设我们有一个名为Person的资源：

{
   "id": 12,
   "name":{
          "first":"Angie",
          "last": "Smith",
          "middle": "joy",
          "maiden": "crowly",
    },
    "address": {
          "street": "1122 Something St.",
          ..and so on...
    },
... and so on
}

假设参数列表相当长。 假设我有一个 API 消费者，他在创建 API 设计时只想要几个字段，比如 id 和 name.first。 我假设允许这样的内容是很常见的：

/person?fields=id,name 其中 fields 表示我只想要这些字段。

我的问题是，那么 Person 资源应该返回所有字段和 null，只返回具有值的那些字段，还是仅返回带有 id 和 name 的 Person 表示，并从后端动态地删除所有其他参数。

看起来方案 #2 更加简洁，但它在 REST 中是否合理，或者人们通常会返回所有其他字段（以确保我们保持结构/模式的一致性/可靠性）并将其设置为 null 值？

- PositiveGuy

Answer 1

正如您建议的那样，选项2更加简洁，并且在REST中这样做是有意义的。 添加null会破坏部分响应的目的，因为它使响应体比必要的要大。 您所描述的用例的示例在Google开发者论坛上展示；请参见Partial Response部分。

- pelumi

---

优秀的链接，这正是我一直在寻找的！我正在努力让我们的网络团队理解，我们正在构建一个REST API，而不是“嘿，平台团队，你需要根据我的应用程序组件结构创建API合同”。不，我们为您提供所需的内容，但我们有一些惯例，我们希望您遵守以获取我们的API信息。什么鬼！好吧，网络团队，你们是说你们正在设计我们的API？这就是我现在正在处理的垃圾。我告诉他们，最终您将能够指定字段子集（部分），但我们刚刚开始这个API。 - PositiveGuy

有时候我真希望自己拥有一家咖啡店，不必再忍受网络团队的无知。这些事情太过令人紧张了，我们甚至不能在设计方面建设性地达成共识。 - PositiveGuy

Answer 2

你所谈论的是同一资源的不同表现形式。这两种表现形式都是有效的，但我认为第二种更加合理，因为响应更小，如果你不想显示值，通常也不需要属性名称。

- inf3rno

Answer 3

为了进一步扩展之前两个非常好的关于部分响应的回答，您也可以考虑使用头部 Prefer 而不是使用查询参数 fields 。

有关更多详细信息，请参见以下链接：

• 规范：https://www.rfc-editor.org/rfc/rfc7240
• Irakli Nadareishvili在此主题上撰写了一篇很棒的博客文章：http://www.freshblurbs.com/blog/2015/06/25/api-representations-prefer.html

希望这能帮助您， Thierry

- Thierry Templier