Який найкращий спосіб повернути масив як відповідь у API RESTful?

Припустимо, у нас є такі ресурси,

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?

На практиці другий варіант - найкраща практика. Причина цього полягає в тому, що ви взагалі не можете розширити ресурс, коли просто повернете масив.

Наприклад: Якщо вам потрібно додати кількість всіх записів, ви вже виконали лише підхід до масиву.

Якщо це відбувається в одному списку api, тоді ви хочете підтримувати його послідовно, тому зробіть все об'єктом, тоді ваш api стає більш послідовним і простішим у використанні для розробників.

Наприклад: Скажімо, розробник пише загальний код, щоб використовувати ваш api для показу сторінок списку та деталей. Він не хоче створювати виняток, тому що іноді це масив, а іноді це об'єкт із властивістю списку.

Ця відповідь загалом не має нічого спільного з принципами щодо відпочинку, гетеоас та інших протоколів, але просто реальна щодо даних, які потрібно надіслати клієнту. Якщо ви вирішили наслідувати, наприклад, hateos, тоді, звичайно, дотримуйтесь їхніх стандартів (що також є об'єктами btw).

І те й інше

[{"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.

Словник з єдиним безглуздим ключем "список" та значенням масиву є безглуздим - натомість поверніть масив.

Якщо одна і та ж служба може повернути книги, компакт-диски або DVD-диски, ви можете повернути словник з клавішею "книги" та значенням масиву. Можливо, є ще одна клавіша "DVD" з масивом DVD. Наприклад, якщо клієнт може запитати перелік усіх своїх покупок.

Якщо ви впевнені, що відповідь буде трактуватися лише як перелік книг (якщо в запиті сказано "дайте мені список книг"), тоді просто масив буде нормальним.

Другий варіант також є кращим методом з міркувань безпеки. У старих браузерах є вразливість безпеки, яка дозволяє іншим кодом 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"}
    ]

}}