在RESTful API中返回数组作为响应的最佳方法是什么？

Question

假设我们有这样的资源，

book:
    type: object
    properties:
        author: {type: string}
        isbn: {type: string}
        title: {type: string}

books:
    type: array
    items: book

因此，当有人在图书资源上生成GET时，我们将返回以下内容

[{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
 {"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]

我从工作人员那里听说，推荐的REST实践是始终将响应作为JSON对象返回，这意味着我们的books模式将如下所示，

books:
    type: object
    properties:
        list:
            type: array
            items: book

所以，现在，反应会是这样的，

{
    "list": [{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
             {"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]
}

这其中哪一个是最好的休息练习？

Answer 1

在实践中，第二个选择是最佳做法。这样做的原因是，当您只返回一个数组时，您根本无法扩展资源。

例如:如果您需要添加所有记录的计数，那么您已经完成了只使用数组的方法。

如果这种情况发生在一个列表api中，那么您希望保持它的一致性，因此让所有的对象都成为一个对象，那么您的api就会变得更加一致，更容易为开发人员使用。

例如:假设开发人员编写通用代码来使用api显示列表和详细信息页。他不想构建一个异常，因为有时它是一个数组，有时它是一个带有list属性的对象。

这个答案总的来说与rest、HATEOAS和其他协议的原则无关，而仅仅是关于您需要发送到客户端的数据的真实情况。如果您决定遵循例如，HATEOAS，那么，当然，坚持他们的标准(这也是对象顺便)。

Answer 2

两者都有

[{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},{"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]

和

{
    "list": [{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
         {"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]
}

是有效的Json。我不认为你应该添加“列表”，如果它不需要，它甚至可能是混淆，因为后面的是一个数组，而不是一个列表。

最好的休息练习？API应该对Accept中的任何设置给予适当的响应，并提供良好的文档。

Answer 3

出于安全原因，第二种选择也是首选方法。旧浏览器存在一个安全漏洞，如果数据作为JSON数组返回，则允许网页上的其他javascript代码窃取数据。因此，从历史上看，最佳实践是不返回JSON数组。事实上，有些框架的"json-ify“函数在传入数组时默认选择选项2。

https://stackoverflow.com/questions/3503102/what-are-top-level-json-arrays-and-why-are-they-a-security-risk

http://ejohn.org/blog/re-securing-json/