我应该为 REST API 集合使用数组还是对象？

Question

我的 API 包含一个 Book 实体，它代表几种可能的 BookContent 的集合，具体取决于语言。 BookContent 是另一个具有属性 Title 和 Content 的实体，它们都依赖于 Language.

Book 应该像这样：

1)

[
  {
     "language": "English",
     "title": "First title",
     "content": "First content"
  },
  {
     "language": "French",
     "title": "Premier titre",
     "content": "Premier contenu"
  }
]

或喜欢：

2)

{
  "English": {
     "title": "First title",
     "content": "First content"
  },
  "French": {
     "title": "Premier titre",
     "content": "Premier contenu"
  }
}

选项1):

产生"self-contained"个元素，即每个对象包含所有信息。
language 属性可以包含任何 Unicode 字符（而作为键则不能）。
是唯一可用的选项。
在两个实体之间创建更清晰的分隔。例如，如果我们决定不再嵌入 BookContent 实体，而只嵌入 return BookContent ID，则可以更轻松地用 ID 替换每个元素。
对于使用我的 API 的开发人员来说可能更熟悉，因为我相信在其他 REST API 中更常见到这种结构。

选项2):

生成更小的元素。
可以更快地根据语言查找元素，而无需遍历整个集合。

这是一个一般性问题，用于了解哪个看起来更像 "best practice"，不假设客户端如何 querying/using REST API，也不假设性能有多重要相对于灵活性等

哪个选项通常更常见 "best practice"？

Answer 1

您在问题中陈述：

This is a general question to know which one looks more like a "best practice", with no assumption on how the clients are querying/using the REST API.

您正在编写旨在帮助客户获取信息的 REST 服务 - 如果这不是您的目标，那么编写它就毫无意义。因此，您需要回答的最重要的问题是 "what information do clients want?"。的答案将决定您的数据结构，而不是 "which one looks better?" - 我们不是您服务的最终用户。

个人，我会选择第一个，只是因为在我的对象中有一个名为 books.English 的数组似乎是错误的，它也允许语言带有 A-Z 之外的字符，并迎合语言未知（或混合）的书籍。如果单本书的简单性是关键（并且语言列表定义明确且有限），那么请考虑：

[
    {
        "language": "English",
        "books": [{
            "title": "First title",
            "content": "First content"
        }]
    },
    {
        "language": "French",
        "books": [{
            "title": "Premier titre",
            "content": "Premier contenu"
        }]
    }
]

然而，从本质上讲，除了 "make them useful" 之外，对于您正在构建的数据结构没有单一的最佳实践。

我应该为 REST API 集合使用数组还是对象？

Should I use an array or an object for REST API collections?

collections

rest

model