День 1342. #ЗаметкиНаПолях
Разработка API для Людей.
Часть 2. Сообщения Об Ошибках. Начало
Часть 1. Идентификаторы Объектов
Сообщения об ошибках похожи на письма от налоговых органов. Вы бы предпочли не получать их, но, когда получаете, лучше, чтобы они ясно говорили, что делать дальше.
Хорошие сообщения об ошибках — часто недооцениваемая часть API. Но они так же важны для изучения вашего API, как документация или примеры. Вот пример ответа API:
{
status: 200,
body: {
message: "Ошибка"
}
}
Оно кажется странным. Давайте рассмотрим, что здесь не так.
1. Отправляйте правильный код ответа
Выше это ошибка или нет? В сообщении говорится, что да, но код ответа 200 говорит, что всё в порядке. Это не только сбивает с толку, но и опасно. Большинство систем мониторинга ошибок сначала смотрят на код ответа, а затем пытаются проанализировать тело сообщения. Эта ошибка, скорее всего, будет «помещена в папку «OK»» и проигнорирована.
Коды ответа предназначены для машин, сообщения об ошибках — для людей. Необходимо устанавливать соответствующий код ошибки при возврате ответа из API.
2. Добавьте описание
Большинство людей согласятся с тем, что сообщение «Ошибка» так же полезно, как и вообще отсутствие сообщения. Код состояния ответа уже должен сообщить вам, произошла ошибка или нет, сообщение должно быть точным и помогать решить проблему.
Может показаться заманчивым иметь расплывчатые сообщения, чтобы скрыть от конечного пользователя любые детали реализации, однако помните, кто ваша аудитория. API предназначены для разработчиков, и они захотят точно знать, что пошло не так. Разработчики приложений должны отображать дружелюбное сообщение об ошибке, если она появляется, конечному пользователю. Получение сообщения «Произошла ошибка» может быть приемлемым, если вы сами являетесь конечным пользователем приложения, поскольку от вас не ожидают отладки проблемы (хотя это всё равно сбивает с толку). А разработчика приложения такой ответ скорее всего просто выведет из себя.
Изменим сообщение из предыдущего примера:
{
status: 404,
body: {
error: {
message: "Клиент не найден"
}
}
}
- У нас есть соответствующий код ответа: 404, ресурс не найден.
- Сообщение ясно: был запрос, который пытался получить клиента, и он не удался, потому что клиент не может быть найден.
- Сообщение об ошибке заключено в объект ошибки, что немного упрощает работу с ошибкой. Даже без кода ответа вы можете просто проверять наличие body.error, чтобы увидеть, произошла ли ошибка.
Уже лучше, но ещё есть куда расти. Ошибка описывает проблему, но по сути она бесполезна.
Окончание следует…
Источник: https://dev.to/stripe/designing-apis-for-humans-error-messages-94p
