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

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

Полная спецификация OpenAPI 3 отображается в реальном времени ниже на этой странице — каждая конечная точка, параметр и формат ответа, заново генерируемые из исходного кода бэкенда при каждом релизе.

Базовый URL¶

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

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

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

http://localhost:8920/api/v1

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

Интерактивный справочник OpenAPI¶

Интерактивный Swagger UI ниже генерируется напрямую из исходников FastAPI при каждом релизе и поставляется вместе с руководством пользователя — запущенный бэкенд для просмотра не нужен. Используйте поле фильтра, чтобы сузить список конечных точек по тегу, разверните любую операцию, чтобы увидеть параметры, схемы запроса/ответа и примеры. Сырую спецификацию также можно скачать в JSON по адресу /api/openapi.json — для генераторов кода вроде openapi-generator-cli.

Опробовать конечные точки на собственном экземпляре

«Try it out» здесь намеренно отключён — сайт документации не проксирует ваш API. Чтобы отправлять реальные запросы, запустите Turbo EA в режиме разработки (ENVIRONMENT=development) и откройте /api/docs на своём экземпляре: нажмите Authorize, вставьте JWT (без префикса Bearer) и используйте Try it out. В продакшене эти точки отключены ради безопасности; эта страница остаётся справочником только для чтения.

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

Все конечные точки, кроме /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": "you@example.com", "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, токен действительный, но пользователю не хватает требуемого разрешения. Реестр разрешений приведён на странице Пользователи и роли.

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

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

Префикс	Назначение
`/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`	Полнотекстовый фильтр (где поддерживается)

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

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

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

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

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

# Скачать схему (запущенный экземпляр не требуется)
curl https://docs.turbo-ea.org/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` и перезапустите бэкенд либо используйте интерактивный справочник выше.
Справочник выше отображается пустым	Проверьте консоль браузера — встраивание загружает `/api/openapi.json`; корпоративные прокси или строгие блокировщики иногда блокируют скрипты с CDN.
`401 Unauthorized`	Токен отсутствует, повреждён или истёк. Аутентифицируйтесь заново через `/auth/login` или `/auth/refresh`.
`403 Forbidden`	Токен действительный, но у пользователя нет нужного разрешения. Проверьте роль на странице Пользователи и роли.
`422 Unprocessable Entity`	Не прошла валидация Pydantic. В теле ответа перечислены недопустимые поля и причины.
Ошибки CORS из браузерного приложения	Добавьте источник фронтенда в `ALLOWED_ORIGINS` в `.env` и перезапустите бэкенд.