🪲 Документирование ошибок в REST API: практическое руководство для системного аналитика 🪲

🔗 Ссылка на полную статью

Проектирование API – это не только про описание успешных запросов и ответов, но и продуманная обработка ошибок.

Зачастую ошибки начинают всерьез обсуждать лишь после того, как тестировщик пишет в чат «ничего не работает» или «а это нормальное поведение?».

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


Что важно знать про ошибки в REST API:

✅ HTTP-код ошибки
Возвращается «снаружи» тела ответа.

Список HTTP-кодов стандартизирован (RFC 9110):
▫️ 2XX – ошибки нет, запрос принят и обработан успешно,
▫️ 4XX – ошибки на стороне клиента (проблемы с форматом или структурой запроса),
▫️ 5XX – на стороне сервера (проблемы во внутренней логике работы сервера - обращения в БД, проверки данных и другие)

👉 Полный перечень на русском


✅ Response Body: JSON-сообщение в дополнение к HTTP-коду
Стандартная структура сообщения об ошибке делает API понятным и удобным.

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

Пример:

{
"error": "2020_VALIDATION_ERROR",
"message": "Данные не прошли валидацию.",
"details": {
"email": "Некорректный формат email.",
"age": "Возраст должен быть положительным числом."
},
"traceId": "c82f3d9b-12f0-487b-9eae-1d234e9f9123"
}

✅ Стандарт «Problem Details» (RFC 7807/9457) по проектированию ошибок в API
Предлагает единый формат JSON для сообщений об ошибках (MIME-тип application/problem+json).
Обновлен в 2023 году.

👉 Стоит сохранить ссылку на него в закладки.


✅ Примеры API-документации с примерами описания ошибок
👉 ЦИАН API
👉 Wieldberries API



Всю информацию с примерами собрала для вас в полном практическом руководстве:

🔗 Ссылка

Доступна в блоге GetAnalyst 🤝

#RestApiGA