Использование множества кодов состояния HTTP

Если вы не являетесь экспертом в области REST, вы, вероятно, снова и снова используете в своих ответах одни и те же HTTP-коды, в основном 200, 404 и 500. При использовании аутентификации вы можете добавить 401 и 403; если использовать перенаправления 301 и 302, это может быть все. Но диапазон возможных кодов состояния намного шире и может значительно улучшить семантику. Хотя во многих дискуссиях о REST основное внимание уделяется сущностям и методам, использование правильных кодов состояния ответа может выделить ваш API.

201: Создано

Многие приложения позволяют создавать объекты: учетные записи, заказы, что у вас есть. В общем, используется код состояния HTTP 200, и этого достаточно. Однако код 201 более точен и подходит лучше:

Код ответа HTTP 201 Created указывает на то, что запрос был выполнен успешно и привел к созданию ресурса. Новый ресурс эффективно создается до того, как этот ответ будет отправлен обратно. и новый ресурс возвращается в теле сообщения, его местоположение определяется либо URL-адресом запроса, либо содержимым заголовка Location.

-- веб-документы MDN

205: Сбросить содержание

Аутентификация на основе форм может быть успешной или неудачной. В случае сбоя обычное поведение состоит в том, чтобы снова отобразить форму со всеми очищенными полями.

Угадай, что? Код состояния 205 предназначен для этого:

Статус ответа HTTP 205 Reset Content указывает клиенту сбросить представление документа, например, очистить содержимое формы, сбросить состояние холста или обновить пользовательский интерфейс.

-- веб-документы MDN

428: требуется предварительное условие

При использовании оптимистической блокировки проверка может завершиться ошибкой во время обновления, поскольку данные уже были обновлены кем-то другим. По умолчанию фреймворки (например, Hibernate) в этом случае выдают исключение. Разработчики, в свою очередь, это ловят и выводят красивое информационное окно с просьбой перезагрузить страницу и повторно ввести данные.

Давайте проверим код состояния 428:

Исходный сервер требует, чтобы запрос был условным. Предназначено для предотвращения проблемы «потерянных обновлений», когда клиент ПОЛУЧАЕТ состояние ресурса, изменяет его и отправляет обратно на сервер, когда тем временем третья сторона изменила состояние на сервере, что привело к конфликту.

веб-документы MDN

Код точно описывает конфликтный случай при оптимистической блокировке!

Обратите внимание, что RFC 6585 упоминает слово условный и показывает пример используя заголовок If-Match. Однако в нем не указано, как именно достичь этого условия.

409: Конфликт

Интересно, что код 409 гласит:

Код ответа HTTP 409 Conflict указывает на конфликт запроса с текущим состоянием сервера.

-- веб-документы MDN

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

410: пропало

В большинстве случаев, когда вы ПОЛУЧАЕТЕ ресурс, который не найден, сервер возвращает код 404. Что, если ресурс существовал раньше, но больше не существует? Интересно, что есть альтернатива для конкретного варианта использования: об этом может сказать семантика возвращаемого HTTP-кода. Именно по этой причине 410.

Код ответа клиента HTTP 410 Gone указывает на то, что доступ к целевому ресурсу больше не доступен на исходном сервере и что это состояние, вероятно, будет постоянным.

Если вы не знаете, является ли это состояние временным или постоянным, вместо этого следует использовать код состояния 404.

-- веб-документы MDN

300: Несколько вариантов

ПРЕДУПРЕЖДЕНИЕ. Это кажется немного надуманным, но спецификация IETF подходит для этого случая.

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

Например, это ответ при доступе к приводу Spring Boot:

{
  "_links": {
    "self": {
      "href": "http://localhost:8080/manage",
      "templated": false
    },
    "beans": {
      "href": "http://localhost:8080/manage/beans",
      "templated": false
    },
    "health": {
      "href": "http://localhost:8080/manage/health",
      "templated": false
    },
    "metrics": {
      "href": "http://localhost:8080/manage/metrics",
      "templated": false
    },
  }
}

В этом месте нет обычных ресурсов. Сервер предоставляет набор ресурсов, каждый из которых имеет выделенный идентификатор. Похоже на совпадение с кодом статуса 300:

[... ] сервер ДОЛЖЕН генерировать полезная нагрузка в ответе 300, содержащем список представлений метаданные и ссылки URI, из которых пользователь или пользовательский агент может выберите наиболее предпочтительный.

-- IETF HTTP 1.1: семантика и контент

Заключение

Как правило, определенные статусы HTTP имеют смысл только при наличии доступа к серверной части REST из внешнего интерфейса JavaScript. Например, сброс формы (205) не имеет смысла, если сервер генерирует страницу.

Проблема с этими кодами связана с семантикой: они подвержены множеству интерпретаций. Почему вы решили использовать 409 вместо 428? В конце концов, это может быть вопрос моей интерпретации, а не вашей.

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

Дальше:

* Коды состояния ответа HTTP * Список кодов состояния HTTP * Серия сообщений о кодах состояния HTTP * Проблема кодов состояния HTTP

Первоначально опубликовано на странице Знаток Java, 23 апреля 2023 г.