Как документировать ошибки в API?
Сегодня про то, что часто пропускают и не особо продумывают в современных компаниях - API ошибки.
Типичный кейс, как и с НФТ, что люди просто делают ctrl-c + ctrl-v.
Однако, это классно работает, когда вы занимаетесь доработкой готовой системы, а что делать, если у вас что-то новое? Как быть?
Прежде, чем ответить на этот вопрос, давайте скажу, почему важно думать про ошибки:
✔ Легче анализировать возникающие проблемы,
✔ Это юзер френдли и пользователи и разработчики вам за это скажут только спасибо.
Как описать ошибки, чтобы это было красиво и правильно?
1 Используем стандартизированные коды HTTP
• 400 Bad Request — клиент что-то напутал;
• 401 Unauthorized — нужна аутентификация;
• 404 Not Found — не нашли, что искали;
• 500 Internal Server Error — что-то сломалось на сервере.
➖➖➖
2 Добавляем дополнительную информацию в ответ
Краткость, конечно, сестра таланта, но зачастую код-статуса не всегда информативен и нужна пояснительная бригада, поэтому в ответ можно добавить:
• Уникальный ID ошибки (пусть коллеги ищут её в логах, а не в панике). Только не добавляйте это наружу;
•Чёткое описание проблемы;
• Подсказку, как её исправить.
Если такое возможно 😉
Например,
➖➖➖
3 Придерживайтесь правил, которые приняты в компании.
Формат ошибок должен быть единым для всех эндпоинтов и желательно для всех API. Это позволит поддерживать универсальность обработки этого добра
➖➖➖
Надеюсь с этим понятно, но, чтобы было нагляднее, как можно сделать, то вот парочка примеров от известных компаний:
• Google API: они добавляют у себя детальную информацию об ошибке, код и статус.
➖➖➖
• Stripe: они разделяют ошибки по типам и добавляют пояснение.
• GitHub: эти ребята немного борщат на мой взгляд, но подход интересный. Они добавляют ошибки с подсказками и ссылками на документацию.
➖➖➖
На этом пожалуй все. Делитесь, как у вас оформляют ошибки в компании?