RESTful API дизайн. Що я повинен повернути, якщо немає рядків?

На даний момент я кодую API для соціальної мережі за допомогою Slim Framework. Моє запитання: Які найкращі практики, коли в структурі json немає рядків для повернення?

Скажімо, що цей виклик / v1 / get / movies повертає 2 рядки з назв кінофільму таблиці:

[
    {"name": "Ghostbusters"},
    {"name": "Indiana Jones"}
]

Але тоді я закликаю / v1 / get / books і в цій таблиці немає рядків. Чи повинен я просто повернути порожню структуру?

[
]

... чи краще було б повідомлення та код помилки?

[
    "errors": {
        "message": "no matches found",
        "code": 134
    }
]

Яка краща практика? (API буде використовуватися в додатках для iOS та Android) Дякуємо!

Зазвичай я б повертав кількість записів у результаті як метадані. Я не впевнений, що це нормальна практика REST, але це не так багато додаткових даних, і це дуже точно. Зазвичай існує пагинація для багатьох сервісів, одразу повертати величезний набір результатів недоцільно. Особисто мені дратується, коли є пагинація для невеликих наборів результатів. Якщо вона порожня, поверніться number_of_records : 0та книги як порожній список / масив books : [].

{
    meta: {
        number_of_records : 2,
        records_per_page : 10,
        page : 0
    },
    books : [
        {id:1},
        {id:27}
    ]
}

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

При роботі з пагинацією завжди пам’ятайте про можливість змісту вмісту чи замовлення. Начебто, перший запит приходить, 24 результати, ви повертаєтесь першими 10. Після цього вставляється "нова книга", і тепер у вас є 25 результатів, але з оригінальним запитом вона буде замовлена ​​на 10-му місці. Коли перший користувач запитує другу сторінку, він не отримає "нову книгу". Існують способи вирішення таких проблем, як надання "ідентифікатора запиту", який слід надсилати за допомогою наступних дзвінків API, а потім повернення наступної сторінки зі "старого" набору результатів, який слід якось зберігати і прив'язувати до "ідентифікатора запиту". Альтернативно - додати поле типу "список результатів змінено з першого запиту".

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

Якщо у вас занадто багато даних для обробки одразу , розгляньте можливість повернення "списку ідентифікаторів" з усіма результатами та деталями для деякого фрагменту цього списку та вкажіть API API multi_get / get_by_id_list для ресурсу.

Ваш приклад зламаний. У вас не повинно бути об’єктів json з повторюваними ключами. Що ви шукаєте, це масив із об’єктами фільму, як це:

 [
    {"name": "movie1"}, 
    {"name": "movie2"}
 ]

Цей підхід також відповідає на ваше запитання. Ви повинні повернути порожній масив, коли запит не відповідає:

[]

З іншого боку, якщо ви намагаєтеся отримати певний ресурс фільму, GET api/movie/34і цей фільм не існує, поверніть 404 із відповідним повідомленням про помилку (закодованим json) у тілі

Якщо це JSON, ви дійсно повинні розглянути можливість повернення масиву об’єктів. Це має багато переваг, у тому числі, коли у вас немає записів, це порожній масив.

Отже, коли у вас є записи, ви б поверталися:

    [
        {"name": "Ghostbusters"},
        {"name": "Indiana Jones"}
    ]

І коли у вас немає записів, ви б поверталися:

    [

    ]

Якщо ви успішно виконуєте операцію, але вона не має нічого повертати, наприклад, порожня карта {}чи порожній масив, []я б хотів відповісти кодом відповіді 204, ось уривок із специфікації визначення коду статусу HTTP :

Сервер виконав цей запит, але йому не потрібно повертати тіло об'єкта і, можливо, захоче повернути оновлену інформацію. Відповідь МОЖЕ включати нову або оновлену метейнформацію у вигляді заголовків сутностей, які, якщо вони є, ОБОВ'ЯЗКОВО бути пов'язані із запитаним варіантом

Якщо клієнт є користувальницьким агентом, він НЕ повинен змінювати свій вид документа на той, що спричинив надсилання запиту. Ця відповідь в першу чергу призначена для того, щоб дозволити вводити дії, не проводячи змін у активному перегляді активного документа агента користувача, хоча будь-яка нова або оновлена ​​метеоформація ДОЛЖНА застосовуватися до документа, який наразі знаходиться в активному вікні агента користувача.

Відповідь 204 НЕ МОЖЕ включати тіло повідомлення і, таким чином, завжди закінчується першим порожнім рядком після полів заголовка.

По суті, я рекомендую використовувати 204 в програмах RESTful через HTTP, коли повернути нічого немає.

Проведено розумну кількість роботи над створенням стандартизованого формату API JSON .

Дотримання принципів у цій специфікації означає, що всі повернені ресурси повинні бути фактично "колекціями" (навіть якщо включений лише один ресурс). Це означає, що ваш дзвінок /v1/get/moviesповернеться:

{
    "movies": [
        {"name": "Ghostbusters"},
        {"name": "Indiana Jones"}
    ]
}

Ваш виклик /v1/get/books(який повертає нульові ресурси) повернеться:

{
    "books": []
}

Для вашого конкретного прикладу я рекомендую / v1 / get / books повертати HTTP 200 з порожнім масивом.

Якщо я читаю правильно вашу публікацію, ваш API має намір збирати книги. Метафорично кажучи, у вас є полиця для книг, стелаж для DVD для фільмів та, можливо, інші контейнери, про які ви тут не згадували. Оскільки ви збираєтесь збирати книги, / v1 / get / books - це ваша книжкова полиця. Це означає, що у вашому конкретному прикладі є дійсний ресурс - список книг - який, як правило, порожній.

Причина, в якій я не пропоную повернути HTTP 404, полягає в тому, що полиця все ще є. Наразі книг на ній немає, але це все-таки книжкова полиця. Якщо б це було не книжкова полиця -якщо API не мають наміру збирати книги для приклад- тоді HTTP 404 буде доречно. Але оскільки там є ресурс, ви не повинні сигналізувати про відсутність такого, що це робить HTTP 404. Тому я стверджую, що 200 з порожнім масивом (що означає колекцію) є більш підходящим.

Причина, по якій я не пропоную повернути HTTP 204, полягає в тому, що це підказує, що "Без вмісту" є звичайним станом речей: виконання цієї дії на цьому ресурсі зазвичай нічого не призведе. Ось чому зазвичай використовується як відповідь на DELETE-запити, наприклад: природа видалення загалом означає, що повернути нічого не залишається. Випадок подібний, коли він використовується для відповіді на запити із заголовками родини If-Modified: ви хотіли вмісту лише у тому випадку, якщо ресурс змінився, але його немає, тому я не дам вам жодного вмісту.

Але я стверджую, що для отримання порожньої, але дійсної колекції, HTTP 204 не має сенсу. Якщо в колекції були елементи, то правильне представлення було б масивом цих даних. Тому, коли даних там немає (але колекція є дійсною), правильне представлення - це порожній масив.

Ви дійсно повинні робити лише одну з двох речей

Або поверніть 200 (OK)код статусу та порожній масив у тілі.

Або повернути 204 (NO CONTENT)код статусу та НІ відповідь.

Мені варіант 2 видається більш технічно правильним і відповідає принципам REST та HTTP.

Однак варіант 1 видається більш ефективним для клієнта - оскільки клієнту не потрібна додаткова логіка для розмежування двох кодів (успішного) статусу. Оскільки він знає, що він завжди отримуватиме масив, він просто повинен перевірити, чи не отримав жоден, один чи багато елементів та обробити його належним чином

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

Перше, що слід врахувати, оскільки ви будуєте API RESTful - це повернути відповідний код відповіді. І більш відповідний код відповіді для повідомлення про те, що запит проходив нормально, але запитуваний ресурс наразі недоступний - це поважна 404.

Якщо ви розробили свій API таким чином, що він завжди повертає розумний код відповіді, можливо, вам навіть не потрібно буде повертати тіло, коли ресурс не знайдений. Однак, повернення тіла, особливо читаного для людини, не може зашкодити.

Тут немає «найкращої практики», обидва ваші приклади є довільними, просто виберіть один і будьте послідовні . Розробники ненавидять сюрпризи, якщо /v1/get/moviesповернення, {}коли немає фільмів, тоді ми очікуємо /v1/get/actorsповернення, {}коли немає акторів.

Я не думаю, що правильна відповідь є тією, що позначена.

Відповідь, надана дев'ятою, повинна бути найкращою за справжнім сценарієм REST. Відповідь тіла має бути порожньою, а код статусу http: 204; ресурс існує, але на той момент він не має "вмісту": порожній.

REST HTTP_Status_Codes

Я рекомендую 200 + порожній масив, оскільки це спрощує обробку всіма клієнтами API. 200 + масив означає "я повернув усі дані, які є". Як для коду, який доставляє дані, так і коду, що їх обробляє, кількість елементів буде несуттєвою.

Кожен інший код статусу повинен бути належним чином задокументований і належним чином доставлений сервером і належним чином оброблений клієнтом, і всі ми знаємо, наскільки це можливо.

Була пропозиція повернути статус 204 + порожнє тіло. Це означає , що ви змушуєте кожен одного клієнта стану процесу 204 правильно. Більше того, ви змушуєте їх обробляти відповіді, що не відповідають JSON! Я сподіваюся, що всі розуміють, що лише тому, що на запит отримано відповідь, це не означає, що відповідь надійшла від сервера, коли використовується http, а просто перевірка того, що відповідь JSON обробляє багато з цих випадків.

Я б "Це залежить".

Якщо нуль - розумний результат, поверніть порожній список. Наприклад, якщо ви хочете, щоб усіх співробітників назвали "bob", де "none" є цілком розумним результатом. Якщо це не очікуваний результат, поверніть помилку. Наприклад, отримання історичного списку адрес вулиці для людини, яку ви наймаєте. Вони повинні жити десь, тому результат, мабуть, не є помилкою, а не просто нормальним станом.

Я впевнений, що ви можете посперечатися зі специфікою мого прикладу, але ви розумієте ...

• Перш за все, якщо getу вашій URL-адресі немає ВІДБУДОВОГО, GET має на увазі метод HTTP.
• Якщо ви запитуєте колекцію, як-от GET api/moviesповернути а 200 OKз порожнім масивом [].
• Якщо ви запитуєте певний фільм, як-от GET api/movies/1(де 1ідентифікатор), і він не існує, поверніть а 404 Not Found.

Чому? Ви запитуєте ресурси . Коли ви запитуєте колекцію, сам ресурс (колекція) існує. Отже, a 404- це неправильно. Але якщо ви запитуєте певний фільм, і він не існує, запитуваний ресурс не існує, і ви повинні повернути 404.

Якщо ви повертаєте JSON, краще завжди повертати підрахунок та повідомлення про помилку і, можливо, булеве значення, яке вказало, чи є помилка чи ні, тобто мої стандартні три мета-значення, що повертаються з кожним списком рядків.