Справочник API¶

Turbo EA предоставляет полноценный REST API, на котором держится всё, что можно сделать в веб-интерфейсе. Его можно использовать для автоматизации обновлений инвентаря, интеграции с CI/CD-конвейерами, построения собственных дашбордов или выгрузки данных EA в другие инструменты (BI, GRC, ITSM, табличные процессоры).

Этот же API интерактивно документирован встроенным в FastAPI Swagger UI, поэтому администраторы и разработчики могут просматривать каждую конечную точку, изучать схемы запросов и ответов и пробовать вызовы прямо в браузере.

Базовый URL¶

Все конечные точки API находятся под префиксом /api/v1:

https://your-domain.example.com/api/v1

Локально (стандартная конфигурация Docker):

http://localhost:8920/api/v1

Единственное исключение — конечная точка проверки состояния, смонтированная по адресу /api/health (без префикса версии).

Интерактивный справочник API (Swagger UI)¶

FastAPI автоматически генерирует спецификацию OpenAPI 3 из кода бэкенда и рядом с ней раздаёт интерактивный Swagger UI. Это единственный источник истины для каждой конечной точки, параметра и формата ответа.

URL	Описание
`/api/docs`	Swagger UI — просматривать, искать и пробовать конечные точки прямо в браузере
`/api/redoc`	ReDoc — альтернативный режим документации только для чтения
`/api/openapi.json`	Сырой OpenAPI 3-схема (полезно для генераторов кода вроде `openapi-generator-cli`)

Доступно только в режиме разработки

По соображениям безопасности конечные точки документации API отключены в продакшене. Они отдаются только когда в файле .env задано ENVIRONMENT=development. В производственных развёртываниях схема OpenAPI публично не доступна, но сам API работает абсолютно так же.

Чтобы изучить справочник API продуктивного экземпляра, поднимите локальный Turbo EA в режиме разработки (схема одинакова для всех развёртываний одной и той же версии) или временно переключите ENVIRONMENT=development, перезапустите бэкенд и затем верните настройку обратно.

Как пробовать конечные точки из Swagger UI¶

Откройте /api/docs в браузере.
Нажмите Authorize в правом верхнем углу.
Вставьте действующий JWT (без префикса Bearer) в поле bearerAuth и подтвердите.
Раскройте любую конечную точку, нажмите Try it out, заполните параметры и нажмите Execute.

Swagger отправляет запрос из вашего браузера с вашим токеном, поэтому всё, что доступно через API, доступно и с этой страницы — удобно для разовых административных задач и проверки прав.

Аутентификация¶

Все конечные точки, кроме /auth/*, проверки состояния и публичных веб-порталов, требуют JSON Web Token в заголовке Authorization:

Authorization: Bearer <access_token>

Получение токена¶

Вызовите POST /api/v1/auth/login с электронной почтой и паролем:

curl -X POST https://your-domain.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

В ответе будет access_token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

По умолчанию токены действуют 24 часа (ACCESS_TOKEN_EXPIRE_MINUTES). Используйте POST /api/v1/auth/refresh, чтобы продлить сессию без повторного ввода учётных данных.

Пользователи SSO

Если ваша организация использует единый вход, войти по электронной почте и паролю не получится. Попросите администратора создать сервисную учётную запись с локальным паролем для автоматизации либо извлеките JWT из session storage браузера после обычного входа через SSO (только для разработки).

Использование токена¶

curl https://your-domain.example.com/api/v1/cards \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Разрешения¶

API применяет те же правила RBAC, что и веб-интерфейс. Каждая модифицирующая конечная точка проверяет как роль вызывающего на уровне приложения, так и все стейкхолдер-роли, которые он удерживает на затронутой карточке. Отдельных «API-разрешений» или обходов через сервисные учётки нет — скрипты автоматизации работают с правами того пользователя, чей токен они используют.

Если запрос завершается ошибкой 403 Forbidden, токен действительный, но пользователю не хватает требуемого разрешения. Реестр разрешений приведён на странице Пользователи и роли.

Часто используемые группы конечных точек¶

Полный справочник — в Swagger; ниже краткая карта самых востребованных групп:

Префикс	Назначение
`/auth`	Вход, регистрация, SSO-callback, обновление токена, информация о текущем пользователе
`/cards`	CRUD над карточками (основная сущность), иерархия, история, утверждение, экспорт CSV
`/relations`	CRUD над связями между карточками
`/metamodel`	Типы карточек, поля, разделы, подтипы, типы связей
`/reports`	KPI дашборда, портфолио, матрица, жизненный цикл, зависимости, стоимость, качество данных
`/bpm`	Управление бизнес-процессами — диаграммы, элементы, версии потоков, оценки
`/ppm`	Управление портфелем проектов — инициативы, отчёты о статусе, СДР, задачи, расходы, риски
`/turbolens`	ИИ-аналитика (вендоры, дубликаты, безопасность, архитектурный ИИ)
`/risks`	Реестр рисков EA (фаза G TOGAF)
`/diagrams`	Диаграммы DrawIO
`/soaw`	Документы Statement of Architecture Work
`/adr`	Architecture Decision Records
`/users`, `/roles`	Управление пользователями и ролями (только для администратора)
`/settings`	Настройки приложения (логотип, валюта, SMTP, ИИ, переключатели модулей)
`/servicenow`	Двусторонняя синхронизация с CMDB ServiceNow
`/events`, `/notifications`	Журнал аудита и пользовательские уведомления (включая SSE-поток)

Постраничный вывод, фильтрация и сортировка¶

Конечные точки списков принимают согласованный набор query-параметров:

Параметр	Описание
`page`	Номер страницы (нумерация с 1)
`page_size`	Элементов на страницу (по умолчанию 50, максимум 200)
`sort_by`	Поле сортировки (например, `name`, `updated_at`)
`sort_dir`	`asc` или `desc`
`search`	Полнотекстовый фильтр (где поддерживается)

Фильтры, специфичные для ресурса, описаны для каждой конечной точки в Swagger (например, /cards принимает type, status, parent_id, approval_status).

События в реальном времени (Server-Sent Events)¶

GET /api/v1/events/stream — это долгоживущее SSE-соединение, которое отправляет события по мере их возникновения (карточка создана, обновлена, утверждена и т. д.). Веб-интерфейс использует его, чтобы обновлять бейджи и списки без поллинга. Подписаться может любой HTTP-клиент с поддержкой SSE — это удобно для построения дашбордов в реальном времени или внешних мостов уведомлений.

Генерация кода¶

Поскольку API полностью описан OpenAPI 3, можно генерировать типизированные клиенты на любом популярном языке:

# Скачать схему с экземпляра разработки
curl http://localhost:8920/api/openapi.json -o turbo-ea-openapi.json

# Сгенерировать клиент на Python
openapi-generator-cli generate \
  -i turbo-ea-openapi.json \
  -g python \
  -o ./turbo-ea-client-py

# …или TypeScript, Go, Java, C# и т. п.

Для автоматизации на Python проще всего использовать httpx или requests с вручную написанными вызовами — API достаточно компактен, чтобы генератор окупался редко.

Ограничение частоты запросов¶

Чувствительные к аутентификации конечные точки (вход, регистрация, сброс пароля) ограничены через slowapi для защиты от брутфорса. Остальные конечные точки по умолчанию не имеют лимитов; если нужно сдержать тяжёлый автоматизированный скрипт, делайте это на стороне клиента или за обратным прокси.

Версионирование и стабильность¶

API версионируется через префикс /api/v1. Несовместимое изменение породит параллельный /api/v2.
Внутри v1 аддитивные изменения (новые конечные точки, новые опциональные поля) могут выходить в минорных и патч-релизах. Удаления и изменения контрактов остаются за мажорной версией.
Текущая версия сообщается через GET /api/health, поэтому автоматизация может определять обновления.

Устранение неполадок¶

Проблема	Решение
`/api/docs` возвращает 404	Swagger UI отключён в продакшене. Установите `ENVIRONMENT=development` и перезапустите бэкенд либо используйте экземпляр разработки для просмотра схемы.
`401 Unauthorized`	Токен отсутствует, повреждён или истёк. Аутентифицируйтесь заново через `/auth/login` или `/auth/refresh`.
`403 Forbidden`	Токен действительный, но у пользователя нет нужного разрешения. Проверьте роль на странице Пользователи и роли.
`422 Unprocessable Entity`	Не прошла валидация Pydantic. В теле ответа перечислены недопустимые поля и причины.
Ошибки CORS из браузерного приложения	Добавьте источник фронтенда в `ALLOWED_ORIGINS` в `.env` и перезапустите бэкенд.