Публичный API
Содержание
Публичный API SubQuery (SQUF) позволяет внешним приложениям работать с данными проекта: получать список подключений, изучать схему баз и запрашивать реквизиты подключений с доступом к проекту. Доступ выдаётся по JWT-токену и привязывается к конкретному проекту. Отдельное API работает с задачами dbt.
Для чего нужен API
- интеграция SubQuery с собственными инструментами и пайплайнами;
- автоматическая проверка схемы источников из внешних сервисов;
- безопасное получение реквизитов подключений без ручной передачи ключей.
Авторизация
- Приложение авторизуется JWT-токеном, полученным через СУФ-авторизацию.
- Токен привязан к приложению (
appId), а приложение — к проекту: методы работают только с проектами, к которым приложение привязано. - Без валидного токена любой запрос возвращает ошибку авторизации.
Методы подключений
| Метод | Что возвращает |
|---|---|
getProjectConnections |
список подключений проекта, доступных приложению |
getConnectionMetadata |
дерево базы данных по подключению: схемы и таблицы |
getDescription |
описание таблицы — результат DESCRIBE для подключений ClickHouse |
getSecret |
реквизиты подключения: учётные данные и тип |
Все методы работают только с подключениями, у которых включён проектный доступ (canProjectRead или canProjectWrite).
Ограничения
- Подключения DuckDB (Озеро) через API недоступны — они работают только внутри SubQuery (Озеро и DuckDB).
- Права определяются проектными правами подключения: без проектного чтения список будет пуст, а запросы к методам вернут отказ.
- API предназначен для приложений, а не для прямых пользовательских запросов: ключ выдаётся интеграции, а не участнику команды.
Как получить доступ
Доступ для внешнего приложения настраивается по согласованию: обратитесь в поддержку, передайте идентификатор проекта и опишите интеграцию — приложение привязывают к проекту и выдадут токен.