#️⃣ Про нумерацию версий API

Версия — это последовательность цифр, которая определяет поведение API. Идеально, когда версионирование следует схеме семантического версионирования (SemVer).

Формат версии: МАЖОРНАЯ.МИНОРНАЯ.ПАТЧ
Например: 2.3.2

➖Мажорная (первая цифра) — увеличивается при обратно несовместимых изменениях, которые могут сломать старые интеграции
Пример: удалено поле или добавлено новое обязательное поле

➖Минорная (вторая цифра) — увеличивается при добавлении новой функциональности с сохранением обратной совместимости
Пример: появилось новое необязательное поле

➖Патч (третья цифра) — увеличивается для исправления ошибок, не влияющих на интерфейс
Пример: исправлена ошибка валидации или опечатка в документации

🤨 А что такое v1 и v2 в адресе API?

В URL часто указывают только мажорную версию — это называется «версионирование через URI».

Пример:
https://api.test.com/v1/customers/
https://api.test.com/v2/customers/
Это позволяет клиентам подключаться к конкретной мажорной версии и не ломать интеграции при глобальных обновлениях.

❕ Важные моменты

➖Переход на новую мажорную версию (v1 → v2) требует доработок в вашем коде
➖Минорные версии и патчи обычно не отражаются в URL — их можно увидеть в документации API
➖Хорошая практика — явно указывать актуальную версию и помечать устаревшие версии как deprecated

🍀 Наглядный пример изменений между версиями

✅v1:
GET /v1/customer

{
  "id": 123,
  "name": "Тест Тестович"
}

✅v2:
GET /v2/customer

{
  "id": 123,
  "first_name": "Тест",
  "last_name": "Тестович"
}

В v2 мажорная версия изменилась, так как структура ответа несовместима с v1 — вместо name появились first_name и last_name.

🖥 Шаблон промта для создания sequence-диаграмм

Ты — опытный software architect и аналитик. 
1. Контекст проекта:
*   Название системы/сервиса: [Краткое название вашего сервиса, например, "Сервис рекомендации книг"]
*   Основная цель системы: [Одно-два предложения о том, что делает система, например, "Предоставляет персонализированные рекомендации книг на основе истории чтения пользователя".]
*   Для кого диаграмма: [Я/команда разработчиков/менеджмент] — Уровень детализации должен быть [техническим/обзорным].

2. Участники процесса (Actors & Components):
*   Инициатор (Actor): [Кто начинает процесс? Например: Пользователь, Внешняя система, Администратор]
*   Основные компоненты системы: [Перечислите ключевые внутренние модули, например: Frontend, Backend API, Auth Service, Database, Search Service]
*   Внешние сервисы/API: [Перечислите сторонние системы, с которыми происходит взаимодействие, например: Stripe API, Google Maps API, Email Service]

3. Ключевой сценарий для диаграммы:
*   Название сценария: [Дайте сценарию название, например: "Успешное оформление заказа", "Поиск и фильтрация товаров"]
*   Пошаговое описание основного сценария:
    1.  [Шаг 1, например: Пользователь вводит данные для поиска и нажимает "Найти".]
    2.  [Шаг 2, например: Frontend отправляет запрос на Backend API.]
    3.  [Шаг 3, например: Backend API проверяет авторизацию, обращаясь к Auth Service.]
    4.  [Шаг 4, например: Backend API выполняет запрос к Database.]
    5.  [Шаг 5, например: Backend API обогащает данные, обращаясь к Внешнему API.]
    6.  [Шаг 6, например: Backend API возвращает обработанные данные на Frontend.]
    7.  [Шаг 7, например: Frontend отображает результат пользователю.]

4. Альтернативные потоки и обработка ошибок:
*   Что должно произойти в случае ошибки? [Опишите хотя бы один альтернативный сценарий, например: "Если товара нет в наличии", "Если платеж не прошел", "Если внешний API недоступен".]
*   Логика повторов (retry): [Нужно ли показывать повторные попытки запросов? Да/Нет]
*   Таймауты: [Важно ли отображать таймауты на диаграмме? Да/Нет]

5. Требования к выходной диаграмме:
*   Формат: [Mermaid JS / PlantUML / Текстное описание для ручного рисования] — предпочтительно Mermaid JS.
*   Уровень детализации: [Укажите, какие детали важно включить: HTTP-методы (GET/POST), названия конкретных эндпоинтов (/api/v1/order), формат данных (JSON), коды ответов (200, 404, 500).]
*   Особые пожелания: [Например: "Покажите параллельные запросы", "Используйте группирующие блоки (alt/opt) для условной логики", "Не показывать взаимодействие с кешем".]

---

Пожалуйста, проанализируй описание выше и создай sequence-диаграмму, которая будет полезна для документирования и проектирования системы.

Шаблон промта можно заполнить самостоятельно, а можно — целиком или отдельные пункты отдать на откуп ИИ. Пример использования и диаграмму можно посмотреть тут.

⚫️Бизнес-анализ & IT

⌨️Пример промта и диаграммы, составленных при помощи шаблона

В качестве примера взяла создание сервиса по поиску научных публикаций в области психологии. Админу было лениво самой заполнять шаблон, поэтому попросила заполнить шаблон дипсика на основании моих вводных (и поплатилась за лень несколькими попытками доведения сценария и архитектуры до MVP). Также можно прогонять через ИИ такое описание на предмет поиска несоответствий, ошибок в логике или для оптимизации архитектуры.

❕ Для корпоративных целей используйте инстументы, разрешенные ИБ вашей компании.

Заполненный шаблон для сервиса поиска научных исследований:


1. Контекст проекта:

· Название системы/сервиса: PsychoSearch
· Основная цель системы: Сервис для поиска и предоставления списка научных исследований в области психологии по заданной теме в едином формате "дата — название — авторы".
· Для кого диаграмма: Я/команда разработчиков — Уровень детализации должен быть техническим, но минимально необходимым для MVP.

2. Участники процесса (Actors & Components):

· Инициатор (Actor): Исследователь (Пользователь)
· Основные компоненты системы: Web Frontend, Backend API, Database (для кэширования)
· Внешние сервисы/API: PubMed API, PsycINFO API

3. Ключевой сценарий для диаграммы:

· Название сценария: Успешный поиск статей по теме с кэшированием
· Пошаговое описание основного сценария:
  1. Исследователь вводит тему исследования в поисковую строку Frontend и нажимает "Найти"
  2. Frontend отправляет POST запрос с поисковым запросом на Backend API (/api/search)
  3. Backend API проверяет наличие результатов в кэше (Database)
  4. Если результатов в кэше нет, Backend API параллельно отправляет запросы к PubMed API и PsycINFO API
  5. Внешние API возвращают результаты в своих форматах JSON
  6. Backend API обрабатывает данные: объединяет результаты, убирает дубликаты, форматирует даты и авторов
  7. Backend API сохраняет обработанные результаты в кэш (Database)
  8. Backend API возвращает отформатированный список статей на Frontend
  9. Frontend отображает результаты пользователю

4. Альтернативные потоки и обработка ошибок:

· Что должно произойти в случае ошибки? Если один из внешних API недоступен, система использует данные только от работающего API. Если оба API недоступны, но есть закэшированные данные - использует их.
· Логика повторов (retry): Нет, не показывать повторные попытки для упрощения
· Таймауты: Нет, не отображать таймауты на диаграмме

5. Требования к выходной диаграмме:

· Формат: Mermaid JS
· Уровень детализации: Включить основные HTTP-методы, показать проверку кэша и параллельные запросы к API
· Особые пожелания: Показать альтернативную ветку когда данные есть в кэше, акцент на простоте архитектуры

⚫️Бизнес-анализ & IT