Справочник по API
Canopy предоставляет полноценный REST API, который лежит в основе всего, что можно сделать в веб-интерфейсе. Вы можете использовать его для автоматизации обновлений инвентаря, интеграции с CI/CD-конвейерами, создания пользовательских панелей мониторинга или выгрузки данных EA в другие инструменты (BI, GRC, ITSM, электронные таблицы).
Полная спецификация OpenAPI 3.1 доступна в разделе Конечные точки API боковой панели — каждая конечная точка, параметр и схема ответа, генерируемая из исходного кода бэкенда при каждом выпуске.
Базовый URL
Все конечные точки API находятся под префиксом /api/v1. URL вашей среды Canopy соответствует следующему шаблону:
https://{ваш-slug}-canopy.rhizo-tech.org/api/v1
Замените {ваш-slug} на slug вашей организации, который отображается в вашем аккаунте Rhizo и в URL, который вы используете для доступа к Canopy.
Единственным исключением является конечная точка проверки работоспособности, которая монтируется по адресу /api/health (без префикса версии).
Интерактивный справочник API
Полная спецификация OpenAPI 3.1 доступна в разделе Конечные точки API боковой панели. Каждая страница конечной точки включает интерактивную площадку, где вы можете ввести bearer-токен и выполнять реальные запросы к вашей среде Canopy.
Необработанная спецификация также доступна для загрузки генераторами кода:
https://docs.rhizo-tech.org/api/openapi.json
Чтобы воспользоваться интерактивной площадкой, откройте любую страницу конечной точки в разделе Конечные точки API боковой панели, введите bearer-токен в поле Authorization, заполните параметры и нажмите Send.
Аутентификация
Все конечные точки, кроме /auth/*, проверки работоспособности и публичных веб-портал ов, требуют наличия JSON Web Token в заголовке Authorization:
Authorization: Bearer <access_token>
Получение токена
POST /api/v1/auth/login с вашим email и паролем:
curl -X POST https://{ваш-slug}-canopy.rhizo-tech.org/api/v1/auth/login \
-H "Content-Type: application/json" \
Ответ содержит access_token:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer"
}
Токены действительны в течение 24 часов. Используйте POST /api/v1/auth/refresh для продления сессии без повторного ввода учётных данных.
Если ваша организация использует единый вход (SSO), вы не можете войти с email и паролем через API. Попросите администратора Canopy создать выделенный сервисный аккаунт с локальным паролем для автоматизации.
Использование токена
curl https://{ваш-slug}-canopy.rhizo-tech.org/api/v1/cards \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Права доступа
API применяет те же правила RBAC, что и веб-интерфейс. Каждая мутирующая конечная точка проверяет как роль вызывающего на уровне приложения, так и роли заинтересованных сторон, которые он занимает на затронутой карточке. Отдельных «разрешений API» или обходных путей для сервисных аккаунтов не существует — скрипты автоматизации выполняются с правами пользователя, чей токен они используют.
Если запрос завершается с ошибкой 403 Forbidden, токен действителен, но у пользователя отсутствует необходимое разрешение. Перейдите на страницу Пользователи и роли для ознакомления с реестром разрешений.
Распространённые группы конечных точек
Справочник в боковой панели является полным источником истины; таблица ниже — быстрый обзор наиболее используемых групп:
| Префикс | Назначение |
|---|---|
/auth | Вход, регистрация, обратный вызов SSO, обновление токена, информация о текущем пользователе |
/cards | CRUD карточек (основная сущность), иерархия, история, утверждение, экспорт CSV |
/relations | CRUD связей между карточками |
/metamodel | Типы карточек, поля, разделы, подтипы, типы связей |
/reports | KPI панели, портфель, матрица, жизненный цикл, зависимости, стоимость, качество данных |
/bpm | Управление бизнес-процессами — диаграммы, элементы, версии потока, оценки |
/ppm | Управление портфелем проектов — инициативы, статус-отчёты, WBS, задачи, затраты, риски |
/turbolens | Анализ на основе ИИ (поставщики, дубликаты, архитектурный ИИ) |
/risks | Реестр рисков EA (фаза G TOGAF) |
/diagrams | Диаграммы DrawIO |
/soaw | Документы «Заявление об архитектурных работах» |
/adr | Записи архитектурных решений |
/users, /roles | Управление пользователями и ролями (только для администраторов) |
/settings | Настройки приложения (логотип, валюта, SMTP, ИИ, переключатели модулей) |
/servicenow | Двунаправленная синхронизация с ServiceNow CMDB |
/events, /notifications | Журнал аудита и уведомления пользователей (включая поток SSE) |
Пагинация, фильтрация и сортировка
Конечные точки списков принимают единый набор параметров запроса:
| Параметр | Описание |
|---|---|
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.1, вы можете генерировать типобезопасные клиенты на любом основном языке:
# Загрузить схему
curl https://docs.rhizo-tech.org/api/openapi.json -o canopy-openapi.json
# Сгенерировать Python-клиент
openapi-generator-cli generate \
-i canopy-openapi.json \
-g python \
-o ./canopy-client-py
# ...или TypeScript, Go, Java, C# и т.д.
Для автоматизации на Python простейший путь — использовать httpx или requests с ручными вызовами — API достаточно мал, чтобы генератор редко оправдывал введение зависимости.
Ограничение частоты запросов
Конечные точки, чувствительные к аутентификации (вход, регистрация, сброс пароля), ограничены по частоте для защиты от атак перебором. Другие конечные точки в настоящее время не ограничены; для интенсивных скриптов автоматизации реализуйте ограничение на стороне клиента.
Версионирование и стабильность
- API версионируется через префикс
/api/v1. Несов местимое изменение повлечёт введение/api/v2параллельно. - Внутри
v1аддитивные изменения (новые конечные точки, новые необязательные поля) могут выходить в минорных и патч-релизах. Удаления или изменения контрактов зарезервированы для увеличения мажорной версии. - Текущая версия передаётся в
GET /api/health, что позволяет обнаруживать обновления из автоматизации.
Устранение неполадок
| Проблема | Решение |
|---|---|
401 Unauthorized | Токен отсутствует, имеет неверный формат или истёк срок действия. Повторно аутентифицируйтесь через /auth/login или /auth/refresh. |
403 Forbidden | Токен действителен, но у пользователя недостаточно прав. Проверьте роль пользователя в разделе Пользователи и роли. |
422 Unprocessable Entity | Ошибка валидации Pydantic. Тело ответа содержит список некорректных полей с объяснением причин. |