Салют! Решила еще написать пару постов на тему API и рассказать случай из практики:
Получаю как-то документацию на внешнее API — для интеграции с платёжным сервисом. Открываю Swagger, всё красиво, эндпоинты на месте. Согласовываю интеграцию, передаю в разработку.
Через две недели разработчик приходит с вопросом: “А что возвращает API если платёж завис в статусе pending дольше часа?” И тут выясняется — в документации этого нет вообще. Ни слова.
Хорошая документация — редкость. Поэтому аналитик должен уметь читать её критически, а не просто принимать как есть.
Вот на что я теперь смотрю в первую очередь:
1. Есть ли вообще схема ошибок
Если описаны только успешные ответы — это красный флаг. Спрашиваю прямо: “пришлите список всех кодов ошибок и их тела ответов”. Если в ответ тишина или “ну, обычно 400 и 500” — закладываю время на уточнения в процессе разработки. Они будут точно.
2. Что значит “опциональное” поле на самом деле
Поле помечено как optional. Окей, а что если его не передать?
— Подставится дефолт? — Просто проигнорируется? — Или вернётся ошибка, потому что поле опциональное только формально, а по факту обязательное при определённых условиях?
Третий вариант встречается чаще, чем хотелось бы. Проверяю на реальном запросе, документации на слово не верю.
3. Идемпотентность — спрашиваю прямо
Если интеграция создаёт сущности — платёж, заказ, бронирование — обязательно уточняю: что при повторном запросе с теми же данными? Дубль? Та же сущность вернётся? Для платежей это критично — повторный запрос из-за обрыва сети не должен списать деньги дважды.
Если в документации об этом ни слова, это не значит что идемпотентности нет. Значит, про неё просто забыли написать. Спрашиваю у владельцев API напрямую, не додумываю сама.
4. Лимиты и троттлинг
Сколько запросов в секунду разрешено? Что происходит при превышении — 429 Too Many Requests, как и положено по спецификации? Или, как бывает на практике, сервис просто молча обрывает соединение либо отдаёт 503? Это нужно знать заранее, а не выяснять на проде в пятницу вечером.
5. Версионирование — какая версия актуальна на самом деле
Иногда документация описывает v2, а в реальности эндпоинт всё ещё на v1, потому что миграция не завершена. Смотрю дату последнего обновления документации. Если её нет — тоже звоночек.
6. Тестовая среда — её поведение реально совпадает с продом?
Самое неприятное открытие — когда на тестовом стенде всё работает идеально, а на проде логика чуть другая. Уточняю у поставщика API: гарантируется ли идентичность тестовой и боевой среды, или есть нюансы, о которых стоит знать заранее.
Документация — это обещание. Но обещания не всегда выполняют полностью. Задача аналитика — найти дыры до того, как их найдёт разработчик в проде, а не после.
🧐 Если было полезно, ставьте реакции, буду делиться больше такой информацией))
___________
Источник: @ba_and_sa
💙 BA|SA | 💬 BA|SA