ТЗ на API: что написать, чтобы разработчик не придумывал за вас — 6 июля 2026 г. в 13:20:04.117
ТЗ на 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