ТЗ на 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