Apa cara terbaik untuk mengembalikan array sebagai respons di RESTful API?

Anggaplah kita memiliki sumber daya seperti ini,

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

books:
    type: array
    items: book

Jadi, ketika seseorang membuat GETsumber daya di buku, kami akan mengembalikan yang berikut

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

Saya mendengar dari seseorang di tempat kerja bahwa praktik REST yang disarankan adalah selalu mengembalikan respons sebagai objek JSON, yang berarti skema kami booksakan terlihat seperti ini,

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

Jadi, sekarang, respons akan terlihat seperti ini,

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

Manakah dari ini yang merupakan praktik REST terbaik?

Dalam praktiknya pilihan kedua adalah praktik terbaik. Alasan untuk ini adalah bahwa Anda tidak dapat memperpanjang sumber daya sama sekali ketika Anda hanya mengembalikan array.

Sebagai contoh: Jika Anda perlu menambahkan hitungan semua catatan Anda sudah selesai dengan pendekatan array saja.

Jika itu terjadi dalam satu daftar api maka Anda ingin tetap konsisten sehingga buat semua objek maka api Anda menjadi lebih konsisten dan lebih mudah digunakan untuk pengembang.

Sebagai contoh: Katakanlah seorang pengembang menulis kode generik untuk menggunakan api Anda untuk menampilkan daftar dan halaman detail. Dia tidak ingin membangun pengecualian karena kadang-kadang array dan kadang-kadang objek dengan properti daftar.

Jawaban ini secara total tidak ada hubungannya dengan prinsip-prinsip tentang istirahat, kebencian dan protokol lain tetapi hanya menjadi nyata tentang data yang Anda perlu kirim ke klien. Jika Anda memutuskan untuk mengikuti, misalnya, hateos maka tentu saja berpegang teguh pada standar mereka (yang juga objek btw).

Kedua

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

dan

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

adalah Json yang valid. Saya tidak berpikir Anda harus menambahkan "daftar" jika tidak diperlukan, bahkan mungkin membingungkan karena apa yang mengikutinya adalah sebuah array, bukan daftar.

Praktik REST terbaik? API harus memberikan respons yang tepat untuk apa pun yang diatur dalam header Terima, dan juga dokumentasi yang baik.

Alasan Anda membuat respons Anda sesuai dengan JSON adalah bahwa JSON adalah standar de facto; bahasa apa pun dengan parser JSON dapat dengan mudah menguraikannya, dan jika Anda menggunakan JavaScript, Anda bahkan tidak memerlukan parser karena JavaScript memahaminya secara asli.

Dengan kata lain, buatlah agar sesuai dengan JSON, dan Anda tidak perlu menulis parser Anda sendiri. Lebih lanjut, tidak akan ada kejutan ketika pengembang berikutnya menulis perangkat lunak yang mengkonsumsi layanan.

REST tidak ada hubungannya dengan skema JSON Anda. Skema mana pun dapat diterima, dari perspektif REST.

Kamus dengan "daftar" kunci yang tidak berarti dan nilai array tidak ada artinya - kembalikan array.

Jika layanan yang sama dapat mengembalikan buku, CD atau DVD, maka Anda dapat mengembalikan kamus dengan "buku" kunci dan nilai array. Mungkin ada "DVD" kunci lain dengan berbagai DVD. Misalnya jika seorang pelanggan dapat menanyakan daftar semua pembelian mereka.

Jika Anda yakin bahwa responsnya hanya akan ditafsirkan sebagai daftar buku (jika permintaan mengatakan "berikan saya daftar buku") maka hanya array yang baik-baik saja.

Opsi kedua juga merupakan metode yang dipilih untuk alasan keamanan. Browser yang lebih lama memiliki kerentanan keamanan yang memungkinkan kode javascript lain pada halaman web untuk mencuri data Anda jika dikembalikan sebagai array JSON. Jadi secara historis praktik terbaik adalah tidak mengembalikan array JSON. Bahkan, ada beberapa kerangka kerja yang fungsi "json-ify" memilih opsi 2 secara default ketika Anda meneruskan dalam sebuah array.

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/

keduanya json dan mematuhi REST. Saya akan membuat responsnya lebih deskriptif, dalam kasus Anda, daftar perubahan ke buku. Atau sesuatu seperti ini :

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

}}