RESTful API：如何对 JSON 表示进行建模？答案

【问题标题】：RESTful API: How to model JSON representation?RESTful API：如何对 JSON 表示进行建模？
【发布时间】：2011-02-13 20:00:34
【问题描述】：

我正在为预订应用程序设计一个 RESTful API。您可以索取住宿清单。这就是我真的不知道如何设计 JSON 表示的地方。这是我的 XML 表示：

<?xml version="1.0" encoding="utf-8"?>
<accommodations>
    <accommodation>
        <name>...</name>
        <category>couch</category>
    </accommodation>
    <accommodation>
        <name>...</name>
        <category>room</category>
    </accommodation>
<accommodations>

我第一次尝试将其转换为 JSON 导致了以下输出 (1)：

{
    "0": {
        "name": "...",
        "category": "couch"
    },
    "1": {
        "name": "...",
        "category": "room"
    }
}

但当我查看其他 API 是如何做到的时，我发现看起来更像这样 (2)：

[
    {
        "name": "...",
        "category": "couch" 
    },
    {
        "name": "...",
        "category": "room" 
    }
]

我知道版本 1 是一个对象，版本 2 是一个数组。

但在这种情况下哪一个更好？

【问题讨论】：

标签： xml json api rest

【解决方案1】：

您可以按如下方式对 JSON 进行建模：

{
  "accomodations" : [
    {
      "accomodation" : {
        "name": "...",
        "category": "couch",
        "uri": "http://example.org/accomodations/accomodation_1"
      }
    },
    {
      "accomodation": {
        "name": "...",
        "category": "room",
        "uri": "http://example.org/accomodations/accomodation_2"
      }
    }
  ]
}

您可以在GET http://example.org/accomodations 上返回它然后可以通过POST http://example.org/accomodations 在正文中使用类似以下内容来创建新的住宿：

{
  "accomodation": {
    "name": "...",
    "category": "room"
  }
}

【讨论】：

谢谢，我已经在其他 API 中多次看到过这种情况。但这不是同一件事两次吗？我要求“住宿”（顺便说一句：真的有 2 m）并得到一份住宿清单 - 当然。为什么要重复这个？还是有技术原因？
如果您以后需要向其中添加字段，返回一个对象而不是一个数组会让您更容易。例如，假设您想通过查询参数过滤来自某个酒店的住宿，例如：GET /accommodations?owner=Hilton 您可能希望包含这样的所有者地址：{ "accomodations" : [ /* accomodations here */ ], "owner" : "Hilton", "address" : "Party Street 123", } 因为您已经返回了一个对象，现有客户不会中断。如果你返回一个数组，现有的客户需要适应。
好的，有一天使用这种样式清楚地表明嵌套列表也更容易。例如，当您开始包含住宿的属性列表时，无论如何您都必须切换到这种方法，那么为什么不在主列表中使用它呢。这种方式更加统一。
我认为重复“住宿”没有多大意义；为什么不直接忽略？它仍然是一个 JSON 对象（在 JSON 数组中），可扩展。
这真的不是 JSON。这是 JSON 的 XML 化。它只会让您的开发人员很难理解他们的解析将返回给他们什么（哈希映射的哈希映射而不是每个对象一个哈希映射的列表）。

【解决方案2】：

如果您打算使用键 (1, 2, ...) 作为与服务器通信的标识符，那么字典会更好，否则我会选择数组。唯一的 id 可能是条目中的一个字段。

【讨论】：

【解决方案3】：

坚持2号。

不要在您的 XML 版本之后为您的 JSON 输出建模。

那里的每个主要 API 都使用数组表示。大多数解析库将返回类似列表的实例，这使得操作它们包含的所有对象变得非常容易。

数字 1 是有效的 JSON，但这不是绝大多数开发人员所期望的。

【讨论】：