Разработка API для Людей.
Часть 2. Сообщения Об Ошибках. Окончание
Начало
Часть 1. Идентификаторы Объектов
3. Добавьте полезной информации
Сообщить, в чем заключалась ошибка, — это минимум, но разработчик захочет знать, как её исправить. «Полезный» API старается устранить любые препятствия на пути решения проблемы.
Сообщение «Клиент не найден» даёт нам некоторую информацию относительно того, что пошло не так, но как разработчики API мы знаем, что могли бы дать здесь гораздо больше информации. Для начала давайте укажем, какой клиент не был найден: "Клиент cus_Jop8JpEFz1lsCL не найден".
Это будет особенно полезно при просмотре журналов ошибок, поскольку сообщит, была ли проблема связана с одним конкретным идентификатором или с несколькими. То есть проблема с отдельным клиентом или с кодом, который делает запрос. Кроме того, префикс идентификатора сообщает, был ли это случай использования неправильного типа идентификатора.
Можно добавить и другую информацию:
- был ли в тестовой среде использован идентификатор из производственной среды,
- ожидался ли другой тип (например, «Ожидалось целое число, получена строка»),
- возможно в запросе отсутствует обязательное поле или права доступа – в таком случае добавьте информацию о том, как это исправить (хотя следите за тем, чтобы не дать слишком много информации и не повысить риски взлома системы),
- иногда бывает полезно показать клиенту, какую информацию он действительно отправил.
4. Больше эмпатии
Самая неприятная ошибка - 500. Это означает, что что-то пошло не так на стороне API и, следовательно, не по вине клиента. Если конечный пользователь полагается на ваш API в качестве критически важного для бизнеса процесса, то получение таких ошибок очень расстроит клиента.
В отличие от других ошибок, полная прозрачность здесь нежелательна. Вы должны быть полностью прозрачными в отношении того, что сделал пользователь, чтобы вызвать ошибку, но осторожны с тем, что вы разглашаете относительно того, что пошло не так в вашем API.
Как и в изначальном примере текст «Ошибка 500» так же информативен, как и его отсутствие. Попытайтесь успокоить клиентов сообщением вроде: «Произошла ошибка. Команда разработчиков проинформирована и разбирается с проблемой. Если это продолжится, свяжитесь с нами по адресу …».
Это не решает основную проблему, но помогает смягчить удар, давая пользователю понять, что вы занимаетесь этим, и что у него есть варианты действий, если ошибка повторится.
Итого
Посмотрим на следующее сообщение об ошибке, когда клиент использует производственный ключ доступа в тестовой среде:
{
status: 404,
body: {
error: {
code: "resource_missing",
doc_url: "https://api.com/docs/errors/resource-missing",
message: "Клиент 'cus_Jop8JpEFz1lsCL' не найден. Он существует в производственной среде, но в этом запросе использовалась тестовая среда.",
param: "id",
type: "invalid_request_error"
}
},
headers: {
'api-version': '3.1.1',
}
}
Здесь мы:- Используем правильный код ответа HTTP,
- Оборачиваем ошибку в объект «error»,
- Добавляем полезную информацию: код ошибки и тип ошибки,
- Даём ссылку на документацию,
- Сообщаем версию API,
- Предлагаем вариант решения проблемы
В результате сообщение об ошибке максимально наполнено информацией, так что даже начинающие разработчики смогут решить проблему самостоятельно.
Источник: https://dev.to/stripe/designing-apis-for-humans-error-messages-94p