RESTful API: 如何建模JSON表示？

Question

我正在为预订应用程序设计一个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是一个数组。

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

- janpio

Answer 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"
  }
}

- dafmetal

---

谢谢，我在其他API中已经看到过这个几次了。但这不是重复的吗？我请求“accommodations”（顺便说一下：真的有两个m），然后得到一个列表 - 当然是住宿列表。为什么要重复呢？还是有技术原因吗？ - janpio

返回一个对象而不是数组，如果以后需要添加字段，这将使您更容易。例如，假设您想通过查询参数过滤来自某个酒店的住宿：GET /accommodations?owner=Hilton您可能希望像这样包含所有者的地址：{ "accomodations" : [ /* accomodations here */ ], "owner" : "Hilton", "address" : "Party Street 123", }由于您已经返回了一个对象，因此现有客户端不会出现问题。如果您返回一个数组，则现有客户端需要进行适应。 - dafmetal

好的，使用这种风格工作一天后，清楚地发现嵌套列表也更容易。例如，当您开始包含住宿属性列表时，必须切换到此方法，那么为什么不在主列表上也使用它呢？这样做可以使整个列表更加统一。 - janpio

我不太明白为什么要重复那个“accomodation”，为什么不直接省略呢？它仍然是一个可扩展的JSON对象（在JSON数组中）。 - StaxMan

这真的不是JSON。这是将JSON转换为XML格式。它只会让开发人员很难理解他们的解析器将返回什么（哈希映射的哈希映射，而不是每个对象一个哈希映射的列表）。 - Localist

Answer 2

如果您打算在与服务器进行通信时使用键（1、2、...）作为标识符，则字典更好，否则我会选择数组。唯一的ID可能是一个条目中的字段。

- extraneon

Answer 3

坚持使用第二种方法。

不要将JSON输出模型化为XML版本。

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

第一种方法是有效的JSON，但它并不是您的大多数开发人员所期望的。

- Localist