RESTful APIで応答として配列を返す最良の方法は何ですか？

このようなリソースがあるとします

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

これらのうち、RESTのベストプラクティスはどれですか？

実際には、2番目のオプションがベストプラクティスです。これは、配列を返すだけではリソースをまったく拡張できないためです。

例：すべてのレコードのカウントを追加する必要がある場合、配列のみのアプローチは既に完了しています。

1つのリストAPIでそれが発生する場合は、一貫性を維持してすべてのオブジェクトを作成すると、APIの一貫性が高まり、開発者にとって使いやすくなります。

例：開発者がAPIを使用してリストページと詳細ページを表示するための汎用コードを記述したとします。彼は例外を作成することを望んでいません。なぜなら、それが配列である場合や、リストプロパティを持つオブジェクトである場合があるからです。

この答えは全体として、休息、ハテオアなどのプロトコルに関する原則とは何の関係もありませんが、クライアントに送信する必要のあるデータについては真実です。たとえばhateosに従うことを決めた場合は、当然、それらの標準に準拠します（これもオブジェクトです）。

両方

[{"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です。不要な場合は「リスト」を追加する必要はないと思います。それに続くものはリストではなく配列であるため、紛らわしいかもしれません。

RESTのベストプラクティスは？APIは、Acceptヘッダーに設定されているものに適切な応答を提供し、適切なドキュメントを提供する必要があります。

応答をJSONに準拠させる理由は、JSONが事実上の標準だからです。JSONパーサーを備えたどの言語でも簡単に解析できます。JavaScriptを使用している場合は、JavaScriptがネイティブに理解するため、パーサーは必要ありません。

言い換えれば、JSONに準拠させると、独自のパーサーを記述する必要がなくなります。さらに、次の開発者がサービスを使用するソフトウェアを作成しても驚くことはありません。

RESTはJSONスキーマとは何の関係もありません。RESTの観点からは、どちらのスキーマでも受け入れられます。

単一の無意味なキー「リスト」と配列値を持つ辞書は無意味です-代わりに配列を返します。

同じサービスが書籍、CD、またはDVDを返すことができる場合、キー「books」と配列値を持つ辞書を返すことができます。DVDの配列を持つ別のキー「DVD」がある場合があります。たとえば、顧客がすべての購入のリストを照会できる場合。

応答が書籍のリストとしてのみ解釈されることが確実な場合（リクエストが「書籍のリストをくれ」と言った場合）、配列だけで問題ありません。

2番目のオプションは、セキュリティ上の理由からも好ましい方法です。古いブラウザには、Webページ上の他のJavaScriptコードがJSON配列として返された場合にデータを盗むことができるセキュリティ上の脆弱性があります。そのため、歴史的にベストプラクティスは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/

どちらもjsonであり、RESTに準拠しています。あなたのケースの変更リストで、本の回答をよりわかりやすくします。またはこのようなもの：

{ "responceObject" : {

   results : 2,

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

}}