Каков правильный статус ответа для REST API GET, не возвращающего содержимое?

Question

У меня есть конечная точка, например:

GET /api/customer/primary

Если основной клиент существует, я возвращаю что-то вроде

{
  name: "customerName"
}

Но что, если я отправлю GET, а основной клиент нене существует?

Лучше ли отправить 200 OK с пустым JSON {}

Или лучше отправить только 204 Нет содержимого?

Answer 1

Но что, если я отправлю GET и основной клиент не существует?

Лучше ли отправить 200 OK с пустым JSON {}

ИлиЛучше всего только отправить 204 Нет контента?

Если я правильно интерпретирую ваш вопрос, вы на самом деле не спрашиваете о кодах состояния, а скорее, какую схему следуетвы используете для управления различными делами в вашем API.

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

Так как это будет возможно?Наилучшие варианты обработки, которые я видел, фокусируются на разработке схемы для расширения - новые поля являются необязательными и имеют документированную семантику того, как их следует понимать, если поле отсутствует.

С этой точки зрения

{}

Не похоже на представление отсутствующего объекта - оно выглядит как представление объекта со значениями по умолчанию для всех необязательных полей.

Возможно, вам нужно что-то вроде Maybe или Option - где вместо того, чтобы пообещать отправить объект назад или нет, вы пообещаете отправить обратно коллекцию из нуля или одного объекта.Коллекции, которые я обычно ожидал бы представлять в JSON в виде массива , а не объекта .

[]

Теперь с , что Идея в кармане, я думаю, что разумно решить, что вы возвращаете представление Maybe, где представление None имеет длину в ноль байтов, а представление Some(object) является представлением JSON объекта.

Так что в этом дизайне 204 при возврате None имеет большой смысл, и вы можете пообещать, что, если успешный ответ вернет тело, то что-то там действительно есть.

Здесь есть компромисс - форма списка позволяет потребителям всегда анализировать данные, но они должны делать это, даже когда отправляется None.С другой стороны, использование пустого представления для None экономит парсинг, но требует, чтобы потребитель обращал внимание на длину контента.

Итак, оглядываясь назад на ваши два предложения, я ожидаю, что при использовании 204 будет более успешным долгосрочным подходом.

Другая возможность - вернуть нулевой тип примитива, если вы хотите выразить, что объект недоступен.Это будет сопровождаться ответом 200, поскольку длина содержимого будет составлять четыре байта.

null

Answer 2

404 - соответствующий код состояния для этого.Вы пытаетесь представить «основного клиента» как ресурс, но в некоторых случаях это отношение не существует.Эта ситуация довольно ясна, для запросов GET это должно быть 404.

Это вполне приемлемый способ сообщить об этом.404 может сигнализировать клиенту, что ресурс еще не существует, и, возможно, его можно создать с помощью PUT.

204 No Content, который имеет особое значение и не имеет особого смысла длятвой случай.204 не просто означает, что тело ответа не собирается (Content-Length: 0 может сделать это), но имеет более конкретное приложение для гипермедиа приложений.В частности, он сигнализирует о том, что когда пользователь выполняет действие, которое приводит к 204, представление не должно обновляться.Это имеет смысл, например, для операции «Обновление», где пользователь может иногда сохранять свой прогресс при работе с документом.В отличие от 205 Reset Content, который означает, что «представление» должно быть сброшено, чтобы (возможно) новый документ мог быть создан с нуля.

Большинство приложений не заходят так далеко.Честно говоря, я не видел ни одного.Учитывая это, возвращение 200 с Content-Length: 0 или 204 No Content является почти совершенно неуместным обсуждением.Спецификация HTTP определенно не запрещает 200 OK с Content-Length: 0.

Это было немного касательно.В заключение, 404 сигнализирует, что эта «вещь» не существует, и это уместно здесь.Там нет многократных интерпретаций.Есть люди, которые написали спецификации, те, кто их хорошо читает, и по другую сторону дискуссии люди, которые ошибаются.

Answer 3

HTTP 404 текст статуса («Не найдено») наиболее близок к ситуации, но:

Первая цифра кода состояния определяет класс ответа.Последние две цифры не имеют никакой роли категоризации.Для первой цифры есть 5 значений:

• 1xx: информационный - запрос получен, продолжающийся процесс

• 2xx: успех - действие было успешно выполненополучено, понято и принято

• 3xx: перенаправление - для выполнения запроса необходимо предпринять дальнейшие действия

• 4xx: ошибка клиента -Запрос содержит неверный синтаксис или не может быть выполнен

• 5xx: ошибка сервера - серверу не удалось выполнить явно допустимый запрос

( ссылка )

• На практике 4xx распознается как ошибка, и вполне вероятно, что некоторые предупреждения будут возникать из инфраструктуры сети / безопасности / ведения журналов
• 204 семантическое указывает, что сервер успешно выполнил запрос, и нет никакого дополнительного контента для отправки - не совсем то, что происходит.
  • Обычный вариант использования - вернуть 204 в результате запроса PUT, обновив ресурс .

Поэтому я бырекомендуем использовать:

HTTP 200 с пустым объектом / массивом

, как вы предложили.

HTTP 200, возвращая нулевой объект Например:

"none" (действительный JSON)

или

  {
    "name": "NO_PRIMARY_CUSTOMER"
  }

(реализация такого нулевого объекта зависит от вашего конкретного поведения системы с возвращенными данными)

Пользовательский код HTTP 2xx с пустым результатом

Менее распространенная, но все же работоспособная альтернатива - возвращать пользовательский код HTTP в диапазоне 2xx (например, HTTP 230) с помощьюпустой результат.

Эту опцию следует использовать с особой осторожностью или даже избегать, если API открыт для широкой аудитории, которая может использовать неизвестные инструменты для доступа / мониторинга API.