ТЗ на API: что написать, чтобы разработчик не придумывал за вас

Однажды я получила от разработчика готовый эндпоинт, который работал. Технически. Но в таком формате, что фронт не мог его использовать без дополнительного преобразования. Когда спросила почему — пожал плечами: “в ТЗ не было написано как, я сделал как удобнее”.

И знаете что? Он был прав.

С тех пор у меня есть чеклист того, что обязательно должно быть в ТЗ на API. Делюсь.

1️⃣ Название и назначение

Не “создать API для заказов”, а конкретно:

Эндпоинт: Создание заказа
Используется: мобильное приложение, личный кабинет
Контекст “кто вызывает” влияет на авторизацию и требования к нагрузке.

2️⃣ Метод и URL

POST /api/v1/orders

Точный адрес, метод, версия. Без этого разработчик придумает сам.

3️⃣ Авторизация

Bearer token (JWT)
Authorization: Bearer {token}

Не написали — получите либо открытый эндпоинт, либо неожиданную схему авторизации.

4️⃣ Тело запроса

Каждое поле с типом, обязательностью и ограничениями:

{
  "userId": 123,       // integer, обязательное
  "items": [...],      // array, обязательное, min: 1
  "comment": "..."     // string, необязательное, max: 500
}

Для необязательных полей — что происходит если не передали? Дефолт? Игнорируется? Напишите явно.

5️⃣ Ответ при успехе

HTTP 201 Created
{
  "orderId": 789,
  "status": "created",
  "createdAt": "2026-06-17T10:00:00Z" // UTC, ISO 8601
}


Формат даты фиксируйте явно — иначе получите локальное время сервера и долгие поиски расхождений.

6️⃣ Ошибки — то, что забывают в 80% ТЗ

422 - Не передан обязательный параметр
404 - Пользователь не найден
401 - Нет авторизации
409 - Товар недоступен

Для каждого кода — тело ответа с понятным error code. Договоритесь о едином формате ошибок на весь проект и зафиксируйте один раз.

7️⃣ Бизнес-логика

Самое недооценённое. Структура понятна — но что происходит внутри?

Пишите явно: заказ создаётся только если все товары в наличии, после создания резервируется остаток, уходит email-уведомление. Если этого нет в ТЗ — разработчик придумает сам. Иногда угадывает. Чаще нет.

8️⃣ Нефункциональные требования

Таймаут: не более 2 секунд
Нагрузка: до 100 запросов в минуту



Если нужна защита от дублей — опишите механизм явно через Idempotency-Key в заголовке. Само собой не появится.

Хорошее ТЗ — это не формальность. Это единственный способ получить то, что вы имели в виду, а не то, что разработчик имел в виду за вас 🙂

🧐 Если было полезно, ставьте реакции, буду делиться больше такой информацией))

___________

Источник: @ba_and_sa

💙 BA|SA | 💬 BA|SA

Авторизация по протоколу OAuth 2.0 в интеграциях

⏳ 4 мин | 🟡🟡⚪️

Читать статью | @analysis_it

💙 Analyst IT | 💬 Analyst IT

Как читать чужую документацию на 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

Всем привет! Напоминаю о нашем розыгрыше

Присоединяйтесь и получите шанс выиграть от нас подарочки))

Разыгрывать будем уже сегодня в 17:00 🙂

🎉 Результаты розыгрыша:

🏆 Победители:
1. Роман (@zkhromann)
2. AlexUnit (@AlexxUnit)
3. Tryshch (@Tryshch)

✔️Проверить результаты

Разбираемся с лицензией Redis. И что выбрать продуктовой команде

⏳ 11 мин | 🟡🟡⚪️

Читать статью | @analysis_it

💙 Analyst IT | 💬 Analyst IT

Корпоративная библиотека как система: Как мы выстраивали архитектуру знаний для нашей IT-команды и что из этого вышло?

⏳ 5 мин | 🟡⚪️⚪️

Читать статью | @analysis_it

💙 Analyst IT | 💬 Analyst IT

Переход с 1С: УПП на 1С:ERP: этапы, стоимость и риски

⏳ 6 мин | 🟡⚪️⚪️

Читать статью | @analysis_it

💙 Analyst IT | 💬 Analyst IT

Как использовать Kafka на собеседовании по System Design

⏳ 17 мин | 🟡⚪️⚪️

Читать статью | @analysis_it

💙 Analyst IT | 💬 Analyst IT

Как работать с требованиями которые меняются — без нервов и переработок

Салют! Помню проект, где требования менялись так часто, что я перестала распечатывать документацию — смысла не было. Разработчики смотрели на меня с немым вопросом, я смотрела на бизнес с тем же вопросом.

❗️Тогда поняла: проблема не в том что требования меняются. Они всегда будут меняться. Проблема в том как ты выстраиваешь работу с ними.

Сразу честно: ни один инструмент не спасёт если в компании хаос на уровне управления. Но даже в таких условиях правильный подход помогает выжить с меньшими потерями для себя и команды. И это тоже результат.

Почему требования меняются — без прикрас

— Бизнес не знал чего хочет до конца. Это нормально — люди часто понимают что им нужно только увидев первый результат
— Изменился контекст: рынок, конкурент, законодательство, новый руководитель с другим видением
— Требования были размыты с самого начала — вот это уже наша зона ответственности

Злиться на второй пункт бессмысленно. Над третьим работать — полностью в наших силах.

Что реально помогает (или помогало в моем случае):

1️⃣Фиксируйте договорённости сразу

Любое решение с встречи — в письмо в тот же день. Люди искренне забывают что говорили три недели назад, это не злой умысел.
Иногда такая фиксация воспринимается в штыки: “ты мне не доверяешь?” Я на это отвечала спокойно: “Доверяю, просто у меня плохая память” — обычно разряжало обстановку.

Договорились: ...
Следующий шаг: ...
Жду подтверждения до [дата].



2️⃣Спрашивайте “зачем”, а не “как”

Это работает всегда и везде — просто здравый смысл.
Приходит менеджер: “Хочу менять цвет строк в таблице”. Спрашиваю зачем. Оказывается — хочет видеть просроченные заказы.
Реальное требование: автоматически подсвечивать просрочку. Другая задача, проще и полезнее.
Половина изменений при правильном вопросе превращается в уточнение исходного требования, а не в новую задачу.

3️⃣ Показывайте стоимость изменения

Когда бизнес приходит с правкой, говорю прямо: “Эта правка затрагивает три модуля, сдвигает сроки на неделю. Готовы?”
Важна подача. Не “это дорого и мы не будем делать”, а “давайте я покажу что затронет эта правка — и вы примете решение”. Некоторые заказчики всё равно воспримут это как отказ помочь — но большинство после такого разговора спокойно отправляют правку в следующий релиз.

4️⃣ Приоритизируйте, не складывайте в кучу

Приоритет / Критерий
Срочно и важно / Блокирует работу прямо сейчас
Важно, не срочно / В следующий спринт
Хотелка / В бэклог

Честно: в компаниях где всё “срочно и важно” по умолчанию — эта таблица работает плохо. Но даже там она помогает хотя бы начать разговор о приоритетах.

5️⃣ Договоритесь о правилах на берегу

В начале проекта проговариваю с заказчиком: как обрабатываем изменения, когда правка идёт в текущий релиз, а когда в следующий, кто финальный ЛПР.
Сложность в наших реалиях: ЛПР часто недоступен, меняется или принимает решения в коридоре после планёрки. В таком случае фиксирую хотя бы того кто есть — пусть не идеально, но лучше чем ничего.

❗️И про внутреннее состояние — это важно

Я долго воспринимала каждое изменение как личную неудачу. Значит плохо собрала, не так спросила, недоработала.
Потом поняла: идеальных требований не бывает. Иногда проблема вообще не в аналитике — а в том что решения принимаются спонтанно на самом верху, и никакой инструмент это не исправит.
Наша ценность не в том чтобы зафиксировать всё раз и навсегда. А в том чтобы управлять изменениями так, чтобы команда не сходила с ума и бизнес получал то что реально нужно.

🧐 Если было полезно, ставьте реакции, буду делиться больше такой информацией))
___________

Источник: @ba_and_sa

💙 BA|SA | 💬 BA|SA

4 ошибки в A/B‑тестах, из‑за которых случайный шум выглядит как эффект

⏳ 8 мин | 🟡🟡⚪️

Читать статью | @analysis_it

💙 Analyst IT | 💬 Analyst IT

Можно ли аналитику в 2026 году положиться на ИИ и агентов или ещё нет?

⏳ 15 мин | 🟤🟤⚪️

Перейти | @ba_and_sa

💙 BA|SA | 💬 BA|SA