Какой код состояния HTTP следует использовать для успешных операций UPDATE (PUT) и DELETE в REST API, например, когда продукт успешно обновляется или удаляется?
Для успешных операций UPDATE (PUT) в REST API обычно следует возвращать код состояния HTTP 200 OK, когда операция завершается успешно, а для успешных операций DELETE — HTTP 204 No Content. Эти коды состояния соответствуют соглашениям REST, где коды 2xx указывают на успех, при этом 200 предоставляет детали в теле ответа для обновлений, а 204 сигнализирует об успешном удалении ресурса без возврата содержимого.
Содержание
- Основы кодов статуса REST API
- Операции PUT: Успешные обновления
- Операции DELETE: Успешные удаления
- Альтернативные коды статуса и когда их использовать
- Лучшие практики реализации
- Распространенные ошибки, которых следует избегать
Основы кодов статуса REST API
Коды статуса HTTP — это стандартизированные трехзначные числа, которые указывают на результат HTTP-запроса. В REST API эти коды следуют иерархической структуре:
- 1xx: Информационные ответы
- 2xx: Успешные ответы
- 3xx: Сообщения о перенаправлении
- 4xx: Ошибки клиента
- 5xx: Ошибки сервера
Для успешных операций REST API в основном используют коды 2xx, но конкретный выбранный код зависит от характера операции и ожидаемого ответа от сервера.
Спецификация HTTP/1.1 определяет эти коды статуса, а шаблоны проектирования REST API установили соглашения об их использовании в различных сценариях.
Операции PUT: Успешные обновления
Когда операция PUT успешно обновляет ресурс, сервер может вернуть несколько кодов статуса в зависимости от конкретных обстоятельств:
HTTP 200 OK
Наиболее распространенным ответом для успешных операций PUT является HTTP 200 OK. Этот код состояния указывает, что запрос был успешным, и обычно включает в себя тело ответа, содержащее представление обновленного ресурса.
{
"id": 123,
"name": "Обновленный продукт",
"price": 29.99,
"updated_at": "2024-01-15T10:30:00Z"
}
HTTP 204 No Content
В некоторых случаях, особенно когда клиенту не нужно возвращать представление обновленного ресурса, можно использовать ответ HTTP 204 No Content. Это распространено в операциях обновления, когда клиент уже знает ожидаемое состояние ресурса.
HTTP 201 Created
Если операция PUT создает новый ресурс (вместо обновления существующего), следует вернуть HTTP 201 Created с заголовком Location, указывающим на URI нового ресурса.
Ключевой момент для операций PUT — нужно ли клиенту получать представление обновленного ресурса в теле ответа. Если да, используйте 200 OK; если нет, 204 No Content является подходящим выбором.
Операции DELETE: Успешные удаления
Для операций DELETE коды ответа более straightforward:
HTTP 204 No Content (Рекомендуется)
HTTP 204 No Content — наиболее подходящий код состояния для успешных операций DELETE. Этот код указывает, что запрос был успешным, но серверу не нужно возвращать тело ответа, что имеет смысл, поскольку ресурс был удален.
При получении кода 204 клиент не должен ожидать какого-либо содержимого в теле ответа.
HTTP 200 OK
Некоторые реализации возвращают HTTP 200 OK с телом ответа, указывающим на успешное удаление. Хотя это функционально, это менее распространено и противоречит принципу, согласно которому операции DELETE не должны возвращать представления ресурсов.
HTTP 202 Accepted
Если удаление является асинхронной операцией, требующей времени для завершения, можно вернуть HTTP 202 Accepted. Это указывает, что запрос принят к обработке, но еще не завершен.
Общее правило для операций DELETE — HTTP 204 No Content является стандартным и наиболее подходящим ответом для успешных синхронных удалений.
Альтернативные коды статуса и когда их использовать
Сравнение HTTP 200 OK и 204 No Content
| Код статуса | Случай использования | Тело ответа | Когда использовать |
|---|---|---|---|
| 200 OK | Обновления PUT, когда клиенту нужно представление обновленного ресурса | Да | Когда сервер должен вернуть представление обновленного ресурса |
| 204 No Content | Обновления PUT, когда клиенту не нужно тело ответа | Нет | Когда клиент уже знает состояние ресурса |
| 204 No Content | Операции DELETE | Нет | Стандарт для успешных удалений |
| 201 Created | Операции PUT, создающие новые ресурсы | Опционально | Когда PUT создает, а не обновляет ресурс |
Особые случаи
Условные обновления и удаления:
При использовании условных запросов (ETags, Last-Modified) применяются другие коды статуса:
- HTTP 412 Precondition Failed, когда условия не выполнены
- HTTP 304 Not Modified для условных GET
Пакетные операции:
Для массовых операций рассмотрите:
- HTTP 207 Multi-Status для сценариев частичного успеха/неудачи
- HTTP 200 OK с подробными результатами операций
Лучшие практики реализации
Последовательность — ключевой фактор
Независимо от выбранных кодов статуса, наиболее важной практикой является последовательность во всем вашем API. Все конечные точки, выполняющие схожие операции, должны возвращать одинаковые коды статуса в схожих ситуациях.
Четкая документация
Четко документируйте поведение кодов статуса вашего API, включая:
- Какие коды статуса возвращает каждая конечная точка
- Что означает каждый код статуса в контексте вашего API
- Форматы тела ответа для успешных операций
Используйте правильные заголовки
Включайте соответствующие заголовки в ваши ответы:
- Заголовок
Content-Typeдля ответов с телами - Заголовок
Locationдля создания ресурса (201) - Заголовок
ETagдля условных операций
Обработка крайних случаев
Рассмотрите крайние случаи, такие как:
- Обновление несуществующих ресурсов (возвращать 404 Not Found)
- Удаление уже удаленных ресурсов (возвращать 404 Not Found или 410 Gone)
Распространенные ошибки, которых следует избегать
Непоследовательные коды статуса
Одна из наиболее распространенных ошибок — использование непоследовательных кодов статуса для схожих операций в разных конечных точках. Это сбивает с толку потребителей API и усложняет его использование.
Возврат ненужных тел ответа
Избегайте возврата тел ответа для операций DELETE или операций PUT, когда клиенту не нужно представление обновленного ресурса. Правильно используйте 204 No Content.
Чрезмерное использование 200 OK
Хотя 200 OK безопасен, это не всегда наиболее подходящий выбор. Подумайте, не лучше ли для операций, где нет значимого тела ответа, использовать 204 No Content.
Игнорирование семантики HTTP
Не игнорируйте семантическое значение кодов статуса. Каждый код имеет конкретное значение согласно спецификации HTTP, и отклонение от этих установленных значений может сбивать с толку потребителей API.
Заключение
- Для успешных операций PUT используйте HTTP 200 OK, когда клиенту нужно представление обновленного ресурса, или HTTP 204 No Content, когда тело ответа не требуется.
- Для успешных операций DELETE всегда используйте HTTP 204 No Content, так как это указывает на успешное удаление без необходимости возвращать тело ответа.
- Поддерживайте последовательность во всем вашем API и документируйте поведение кодов статуса четко.
- Избегайте распространенных ошибок, таких как возврат ненужных тел ответов или использование неподходящих кодов статуса, нарушающих семантику HTTP.
- Учитывайте конкретные потребности потребителей вашего API при выборе между 200 OK и 204 No Content для операций обновления.
Следуя этим установленным соглашениям REST API, вы создадите API, которые предсказуемы, интуитивно понятны и соответствуют веб-стандартам, которые ожидают разработчики.