Плохое ТЗ — это не вина одного человека. Это результат работы команды

⏳ 10 мини | 🟡⚪️⚪️

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

💙 Analyst IT | 💬 Analyst IT

Год назад я думал, что ИИ заменит архитектора. Я ошибался

⏳ 15 мин | 🟡⚪️⚪️

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

💙 Analyst IT | 💬 Analyst IT

Салют! Хочу тоже затронуть тему, проектировать REST API и рассказать на своем примере

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

🚨 Давайте разберём REST API нормально — один раз, по-человечески, с примером.

Сначала главное: REST — это не технология, это договорённость

REST — архитектурный стиль. Просто набор правил о том, как клиент и сервер общаются через HTTP. И первое правило, которое нарушают чаще всего — ресурсы именуются существительными, не глаголами.

❌ Так не надо:

POST /getUser
POST /createOrder
GET  /deleteProduct?id=5

✅ Так правильно:

GET    /users/{id}
POST   /orders
DELETE /products/{id}

HTTP-методы сами несут смысл действия — GET получить, POST создать, PUT/PATCH обновить, DELETE удалить. Глагол в URL — это дублирование, которое потом запутает всех, включая вас саму через полгода.

💡 Живой пример: API интернет-магазина

Есть товары, заказы, пользователи. Поехали.

Базовые операции:

GET    /products        — список товаров
GET    /products/{id}   — конкретный товар
POST   /products        — создать товар
PATCH  /products/{id}   — обновить часть данных
DELETE /products/{id}   — удалить товар

Здесь сразу вопрос, который почти никогда не задают вслух: PUT или PATCH?

PUT — заменяет ресурс целиком и обязан быть идемпотентным — то есть хоть десять раз вызови с одними данными, результат одинаковый
PATCH — обновляет только то, что передали

На практике PATCH выигрывает почти всегда — никто не хочет слать весь объект ради изменения одного поля статуса.

Вложенные ресурсы — и вот тут начинается самое интересное

Заказ принадлежит пользователю. Отражаем это в структуре:

GET  /users/{userId}/orders             — все заказы пользователя
GET  /users/{userId}/orders/{orderId}   — конкретный заказ
POST /users/{userId}/orders             — создать заказ

Но если заказы нужны и сами по себе — например, в админке — добавляем отдельно:

GET /orders/{id}

И вот моё личное правило, выстраданное на проектах:

Вложенность глубже двух уровней — тревожный сигнал. Если у вас
/users/{id}/orders/{orderId}/items/{itemId}/reviews — это не REST, это маршрут до боли.

Коды ответов — то, на что аналитики машут рукой зря

“Разработчик разберётся” — нет. Или разберётся по-своему, и тогда фронт получает 200 с телом {"error": true} и тихо плачет.

Минимальный джентльменский набор:

200 - Успешный GET, PATCH, PUT
201 - Успешный POST — ресурс создан
204 - Успешный DELETE — тело пустое
400 - Синтаксически сломанный запрос (битый JSON и т.п.)
401 - Не авторизован 403 - Авторизован, но нет прав 404 - Ресурс не найден 409 - Конфликт (дубль email, например)
422 - Запрос понят, но данные не прошли валидацию
500 - Ошибка сервера

Отдельно про 400 vs 422 — это путают постоянно. 400 — когда запрос синтаксически сломан, сервер вообще не смог его прочитать. 422 — запрос понятен, но внутри что-то не то: поле обязательное, формат не тот, логика не сходится. Для ошибок валидации форм почти всегда нужен именно 422.

И 401 vs 403 — классика жанра: 401 = “кто ты вообще?”, 403 = “знаю кто ты, но нет”.

Формат ошибки — договоритесь до начала разработки

Лучший момент для этого — старт проекта. Худший — когда фронт уже написал сорок обработчиков.

✅ Хорошо:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Поле email обязательно",
    "field": "email"
  }
}

❌ Плохо:
Второй вариант — это не API, это квест.

{
  "status": false,
  "msg": "err"
}

Версионирование — заложите сразу

API когда-нибудь изменится. Поменяется логика, добавятся поля, что-то удалится.
Если не заложить версионирование с самого начала — первое же обновление превратится в боль для всех.

Самый простой и понятный способ:

/api/v1/products
/api/v2/products

___________

Источник: @ba_and_sa

💙 BA|SA | 💬 BA|SA

Системные дашборды для Sigla Vision

⏳ 9 мин | 🟡⚪️⚪️

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

💙 Analyst IT | 💬 Analyst IT

Data Mesh: что это и почему концепция не подходит большинству компаний в России

⏳ 12 мин | 🟡🟡⚪️

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

💙 Analyst IT | 💬 Analyst IT

Дарим подарки нашим подписчикам 🎁

Мы с ребятами решили порадовать вас интересными подарками от наших каналов:

- Внешний жесткий диск
- Настольная игра от Школы Систем Аналист
- Футболка BA | SA

Условия максимально простые:
- подписаться на каналы;
- нажать «участвую».

1. Системный анализ | Ольга Пономарева
2. Business | System analyst
3. Analyst IT

07.07 в 17:00 мы проведем розыгрыш и троим из вас улыбнется удача)))

Как мы переносили интеграции с монолита на микросервис

⏳ 3 мин | 🟡🟡⚪️

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

💙 Analyst IT | 💬 Analyst IT

Агент написал код за 12 секунд и чинил его 40 минут: как я на самом деле сравнила ИИ-агентов

⏳ 6 мин | 🟡🟡⚪️

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

💙 Analyst IT | 💬 Analyst IT

Теория и практика DWH: что такое согласованные факты и измерения по Кимбаллу и зачем они нужны

⏳ 4 мин | 🟡⚪️⚪️

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

💙 Analyst IT | 💬 Analyst IT

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