Статус-коды HTTP — это часть протокола HTTP, используемая для указания результатов выполнения запросов. В контексте проектирования REST API, правильное использование статус-кодов повышает читаемость и удобство использования API, а также помогает в обработке ошибок и мониторинге состояния системы. Вот обзор ключевых статус-кодов и рекомендации по их применению.

Одним из ключевых аспектов REST API является использование HTTP статус-кодов для передачи информации о результате обработки запроса. Правильное применение статус-кодов повышает понятность и удобство использования API. Данная статья рассматривает практические примеры использования наиболее распространенных HTTP статус-кодов в REST API.

Информационные коды (1xx)

Коды класса 1xx указывают на то, что запрос был принят и обработка продолжается. Эти коды редко используются в REST API, но все же важно понимать их назначение.

  • 100 Continue: Сервер получил начальные заголовки запроса, и клиент может продолжать отправку тела запроса. Полезно для проверки того, что сервер готов принять большой запрос без отправки всего тела сразу.

  • 101 Switching Protocols: Сервер соглашается на изменение протокола, как указано в заголовке Upgrade клиента. Обычно используется для перехода от HTTP к WebSocket.

Успешные запросы (2xx)

Коды класса 2xx указывают на успешную обработку запроса сервером. Наиболее часто используемые из них:

Код Описание Применение Практическое применение
200 OK Запрос успешно обработан. Возвращается при успешной обработке GET-запроса, когда запрошенные данные включены в тело ответа. Также может использоваться для подтверждения успешного выполнения PUT или POST-запроса, если необходимо вернуть обновленные или созданные данные. Используйте для подтверждения успешной обработки запроса на чтение (GET), обновление (PUT) или создание (POST). Включайте данные в теле ответа, если это необходимо.
201 Created Новый ресурс был успешно создан. Возвращается в ответ на успешный POST-запрос, создающий новый ресурс. В заголовке Location следует включить URI созданного ресурса. Применяйте для POST-запросов, создающих новые ресурсы. Убедитесь, что URI созданного ресурса указан в заголовке Location.
202 Accepted Запрос был принят, но еще не обработан. Используется для запросов, обработка которых может занять значительное время. Сервер принимает запрос, но еще не завершает его обработку. Полезен для асинхронных операций. Включайте в ответ информацию о статусе или ссылку для проверки состояния выполнения запроса.
204 No Content Запрос успешно выполнен, но в ответе нет содержимого. Используется для подтверждения успешного выполнения запросов PUT или DELETE, когда нет необходимости возвращать тело ответа. Применяйте для PUT и DELETE-запросов, когда не требуется возвращать данные в ответе. Убедитесь, что тело ответа пустое.
206 Partial Content Сервер возвращает часть ресурса, как указано в заголовке Range запроса. Используется при выполнении запросов с диапазоном данных, чтобы вернуть только часть ресурса, например, при подкачке больших файлов. Полезен для реализации подкачки и возобновляемых загрузок. Включайте в ответ заголовок Content-Range с указанием диапазона возвращаемых данных.

Коды перенаправление (3xx)

Коды класса 3xx указывают на то, что для завершения обработки запроса требуется дополнительное действие со стороны клиента, например, перенаправление на другой URL.

Код Описание Применение Практическое применение
301 Moved Permanently Указывает, что ресурс был окончательно перемещен на новый URL. Клиенты должны использовать новый URL в будущем. В заголовке Location указывается новый URI. Применяйте при постоянной смене местоположения ресурса. Это важно для SEO и корректной работы закладок.
302 Found Ресурс временно доступен по другому URL. Клиенты должны продолжать использовать оригинальный URI для будущих запросов. Новый URI указывается в заголовке Location. Полезен при временном перенаправлении, например, во время обслуживания ресурса. Убедитесь, что клиенты понимают, что это временное перенаправление.
303 See Other Ресурс можно найти по другому URI, используя GET-запрос. Полезно при обработке POST-запросов, когда необходимо перенаправить клиент на страницу результатов. Используйте для перенаправления после выполнения POST-запросов на страницу с результатами, например, на страницу подтверждения или просмотра.
304 Not Modified Указывает, что ресурс не изменялся с момента последнего запроса. Используется для эффективного кеширования, позволяя клиенту использовать закешированную версию ресурса без повторного его скачивания. Эффективно при реализации механизма кеширования, снижая нагрузку на сервер и уменьшая время отклика. Клиенты должны использовать заголовки If-Modified-Since или ETag.
307 Temporary Redirect Запрос должен быть повторно отправлен на другой URI, используя тот же метод. В отличие от 302, сохраняет метод запроса. В заголовке Location указывается временный URI. Полезен при временном перенаправлении, когда необходимо сохранить метод запроса (например, POST останется POST).
308 Permanent Redirect Как 301, но требует, чтобы клиент использовал новый URI для всех будущих запросов и сохранял метод запроса. Клиенты должны использовать новый URI для всех будущих запросов. В заголовке Location указывается новый URI. Применяйте при постоянной смене местоположения ресурса. Убедитесь, что клиенты понимают, что это постоянное перенаправление и сохраняют метод запроса.

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

Ошибки на стороне клиента (4xx)

Коды 4xx означают, что запрос не может быть обработан из-за ошибки на стороне клиента:

Код Описание Применение Практическое применение
400 Bad Request Запрос содержит синтаксическую ошибку или передает некорректные данные. Используется, когда запрос не может быть обработан из-за ошибки на стороне клиента, например, неверный формат JSON. Возвращайте этот код, когда сервер не может обработать запрос из-за некорректных данных. Обязательно включайте информацию о природе ошибки в ответе для облегчения отладки клиентом.
401 Unauthorized Клиент не предоставил необходимых данных аутентификации или предоставленные данные не прошли проверку на сервере. Используется, когда запрос требует аутентификации, и либо она отсутствует, либо невалидна. Применяйте для защищенных ресурсов, требующих аутентификации. Возвращайте вместе с заголовком WWW-Authenticate, указывающим способ аутентификации.
403 Forbidden Сервер понял запрос, но отказывает в его выполнении, так как у клиента недостаточно прав доступа к запрашиваемому ресурсу. Используется, когда клиент аутентифицирован, но не имеет прав для доступа к ресурсу. Возвращайте, когда у клиента недостаточно прав доступа. Убедитесь, что причина отказа в доступе ясно описана в ответе.
404 Not Found Запрошенный ресурс не найден на сервере. Используется, когда сервер не может найти запрашиваемый ресурс, например, при обращении к несуществующему URL. Применяйте для отсутствующих ресурсов. Убедитесь, что путь к ресурсу правильно указан в запросе, и предоставьте клиенту информацию о возможных причинах ошибки.
409 Conflict Конфликт в запросе, например, при попытке создания дублирующегося ресурса. Используется, когда запрос не может быть обработан из-за конфликта с текущим состоянием ресурса, например, при попытке создать ресурс, который уже существует. Возвращайте при обнаружении конфликта, например, дублирующегося уникального идентификатора. Включайте подробности конфликта в ответ для облегчения разрешения проблемы клиентом.
422 Unprocessable Entity Сервер понимает запрос, но не может его обработать из-за семантических ошибок. Используется, когда запрос корректен по синтаксису, но содержит логические ошибки, например, некорректные данные для создания ресурса. Применяйте для валидации данных на сервере. Включайте в ответ подробности о том, какие именно данные не прошли проверку и почему.

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

Ошибки на стороне сервера (5xx)

Коды 5xx указывают на то, что запрос не может быть обработан из-за ошибки на стороне сервера. Эти коды сигнализируют клиенту, что проблема возникла не из-за некорректного запроса, а из-за внутренней ошибки сервера.

Код Описание Применение Практическое применение
500 Internal Server Error Сервер столкнулся с непредвиденной ошибкой, которую он не смог обработать. Используется, когда возникает исключение, не предусмотренное логикой приложения, например, ошибка базы данных или некорректная конфигурация сервера. Всегда включайте логирование подробностей ошибки на стороне сервера для последующей диагностики и исправления. Клиентам можно возвращать общий ответ с минимальными деталями, чтобы не раскрывать внутреннюю архитектуру.
501 Not Implemented Сервер не поддерживает функциональность, необходимую для выполнения запроса. Возвращается, когда сервер не распознает метод запроса или не поддерживает его, например, если API не реализует метод DELETE. Полезен для API, которые находятся в стадии разработки или частично реализованы. Клиенты могут использовать этот ответ для определения доступности функционала.
502 Bad Gateway Сервер, действующий как шлюз или прокси, получил некорректный ответ от вышестоящего сервера. Используется в архитектурах с прокси-серверами или балансировщиками нагрузки, когда один из серверов в цепочке возвращает некорректный ответ. Включайте мониторинг и алертинг для отслеживания ошибок шлюза и быстрого реагирования на проблемы в цепочке запросов.
503 Service Unavailable Сервер временно не может обработать запрос из-за перегрузки или проведения технического обслуживания. Используется для указания клиентам на временные проблемы, такие как обновление системы или временные сбои. Часто сопровождается заголовком Retry-After с указанием времени, через которое стоит повторить запрос. Возвращайте с заголовком Retry-After, чтобы указать клиентам, когда лучше повторить запрос. Используйте при плановых работах или временных перегрузках.
504 Gateway Timeout Сервер, действующий как шлюз или прокси, не дождался ответа от вышестоящего сервера в установленное время. Возвращается, когда сервер в цепочке обработки запроса слишком долго не отвечает, что может указывать на проблемы с производительностью или недоступность сервиса. Настройте таймауты и ретраи в ваших сервисах, чтобы минимизировать вероятность возникновения этой ошибки. Используйте для диагностики проблем с задержками между сервисами.
505 HTTP Version Not Supported Сервер не поддерживает версию протокола HTTP, указанную в запросе. Используется, когда клиент отправляет запрос с версией HTTP, которую сервер не может обработать, например, если сервер поддерживает только HTTP/1.1, а запрос использует HTTP/2. Обновите серверную инфраструктуру для поддержки актуальных версий протоколов. Возвращайте этот код, если получаете запросы с устаревшими или неподдерживаемыми версиями HTTP.

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

Рекомендации по использованию статус-кодов

  1. Специфичность: Выбирайте наиболее точный код статуса для каждой ситуации. Это облегчает разработку клиентской части и обработку исключений.
  2. Документация: Четко документируйте использование статус-кодов в вашем API. Это помогает разработчикам понимать ожидаемые ответы и корректно реагировать на них.
  3. Расширяемость: Возможно, потребуется расширение стандартного набора кодов специфическими для вашего приложения. При этом важно не отходить от общепринятых практик и не переопределять уже существующие коды.