Должен ли возвращаться пустой список [] 200/204 или 404 в дизайне Restful API?

Question

Например, есть API-интерфейс restful API GET http://luexu.com/users/{page} для вывода списка пользователей на N-й странице. Предположим, на каждой странице 20 пользователей. Всего в базе 100 пользователей. GET http://luexu.com/users/5 возвращает от 80-го до 100-го пользователя.

Так как насчет запроса GET http://luexu.com/users/10? это из общего числа пользователей. Какой вариант лучше вернуть пустой список, пустой массив [] или 404?

200

{
    "code": 200,
    "msg": "OK",
    "data": []
}

или 204?

{
    "code": 204,
    "msg": "OK",
    "data": []
}

или 404?

{
    "code": 404,
    "msg": "Not Found",
    "data": null
}

Answer 1

так как насчет кода 204?

В HTTP 204 без содержимого означает что-то очень специфическое - тело сообщения имеет длину 0 байт.

Код состояния 204 (без содержимого) указывает, что сервер успешно выполнил запрос и что в теле полезной нагрузки ответа нет дополнительного содержимого для отправки.

Так что вы не должны думать об этом, если отправляете, например, документ в кодировке json.

Если приемлемым представлением ресурса является пустой список, то можно использовать 200 в качестве кода ответа. Например, рассмотрим этот URI для самого переполнения стека.

https://stackoverflow.com/questions/tagged/cqrs+or+domain-driven-design+or+event-sourcing?sort=newest&page=999&pagesize=15

По состоянию на 2019-06-01, с этими тегами было намного меньше, чем 999 страниц вопросов, но у сервера нет проблем с вычислением правильного представления для этой страницы (включая информацию о том, что страница с наибольшим номером 426). Поэтому семантика 200 идеально подходит.

404 означает, что представление для ресурса недоступно. Все коды ответа класса 4xx указывают на ошибку с запросом - в этом случае это говорит о том, что клиент допустил ошибку с URI. Это может быть временным условием (вы не должны сейчас спрашивать об этом ресурсе). Так что это также может быть хорошо, если вы хотите указать, что клиент оставил счастливый путь протокола домена.

Как выбрать? Я начинаю с этого наблюдения в спецификации HTTP

сервер ДОЛЖЕН послать представление, содержащее объяснение ситуации ошибки и является ли это временным или постоянным условием.

Так что же полезно для клиента? Представление проблемы или представление пустой коллекции? Это может быть сложным вопросом, когда одни и те же ресурсы используются для разных целей.

Answer 2

Это один из тех вопросов, на который нет «лучшего» ответа.

Все, что вы можете сделать, это посмотреть на варианты и выбрать то, что лучше всего подходит для вашего сценария.

Как правило, я лично избегаю возврата 404. Причина в том, что неясно, почему вы получили 404. Вы можете получить 404, потому что ваш URL неверен, поэтому, если вы сделаете выбор дизайна, чтобы вернуть 404, когда данных нет, то вы попадаете в неясную ситуацию. Откуда ты знаешь, почему у тебя 404? Это не хорошо.

Возвращение 200 с пустым массивом вполне нормально. Возвращение 204 также отлично.

Важным моментом является выбор, согласованность и документирование выбора, чтобы пользователи вашего API знали, что вы сделали этот выбор и почему.

Последовательность и ясность, стремитесь к этому.

Answer 3

Возвращение 404 не подходит для случаев, когда у вас есть неполная страница (например, у вас 85 пользователей), поэтому я бы выбрал пустой список, 404 лучше, если у вас есть бинарный вопрос, найден ресурс или нет.

Я хотел бы взглянуть на следующий подобный вопрос: Служба отдыха возвращает 404