Урок 042 минуты чтения
Как формировать ответы и выбирать статус-коды?
На этой странице
Кратко
Код ответа должен кратко описывать результат, а JSON — содержать данные или понятное описание ошибки.
Вопрос
Как формировать ответы Express API и выбирать статус-коды для успеха и ошибок?
Успешные ответы
// Получение данных
response.status(200).json(users);
// Создание
response
.status(201)
.location(`/api/users/${createdUser.id}`)
.json(createdUser);
// Удаление без тела
response.status(204).send();| Код | Когда использовать |
|---|---|
200 OK | Успешное чтение или изменение с телом ответа |
201 Created | Ресурс создан |
204 No Content | Действие выполнено, тело не нужно |
Ошибки клиента
| Код | Значение |
|---|---|
400 | Запрос имеет неверный формат |
401 | Пользователь не подтверждён |
403 | Пользователь известен, но действие запрещено |
404 | Ресурс не найден |
409 | Конфликт, например почта уже занята |
422 | Формат понятен, но значения не проходят проверку |
429 | Слишком много запросов |
Команда может выбрать 400 или 422 для ошибок проверки данных. Важнее использовать выбранный подход последовательно.
Ошибки сервера
response.status(500).json({
error: {
code: "INTERNAL_ERROR",
message: "Не удалось выполнить запрос",
},
});Не отправляй клиенту стек вызовов, SQL-запрос или пароль подключения.
Единый формат
Успех:
{
"data": {
"id": 42,
"name": "Анна"
}
}Ошибка:
{
"error": {
"code": "USER_NOT_FOUND",
"message": "Пользователь не найден"
}
}Обёртка data необязательна. Главное — единообразие всего API.
json() или send()
json()преобразует значение в JSON и задаёт правильный тип содержимого;send()подходит для текста, HTML или буфера;- для API чаще используется
json().
Что важно помнить
401— пользователь не подтверждён,403— подтверждён, но действие запрещено.201 Createdсопровождают заголовкомLocationс адресом нового ресурса.- Ответ
204не содержит тела — клиент не должен вызывать на нёмresponse.json(). - Ответ
500не раскрывает стек, SQL и параметры подключения. - Выбор между
400и422для ошибок проверки — соглашение команды; важна последовательность.
Мини-шпаргалка
200— успех,201— создано,204— успех без тела.400— неверный запрос,404— не найдено,409— конфликт.500не должен раскрывать внутренние подробности.- Для созданного ресурса полезен заголовок
Location. - Формат ошибок должен быть одинаковым во всём API.
Документация
Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.