Business | System analyst

Как читать чужую документацию на API, чтобы не наступить на грабли Салют! Решила еще написать пару постов на тему 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