EvoBGP/docs/api.md

REST API: обзор и ссылки

Полный контракт запросов и ответов описан в openapi.yaml (OpenAPI 3.1). Этот файл — источник правды. Краткий контекст и ранние таблицы — в evobgp-api-sketches.md (черновик, не заменяет OpenAPI).

Базовый URL и версия

• Все функциональные маршруты API используют префикс /v1 (например https://api.example.com/v1/modules).
• Версия сборки: GET /v1/version (публичный маршрут, без Bearer).

Публичные маршруты (без Authorization)

Метод	Путь	Назначение
GET	/v1/health	Liveness
GET	/v1/ready	Readiness (зависимости, например БД)
GET	/v1/version	Версия / метаданные сборки

Дополнительно на корне сервера (вне /v1):

Метод	Путь	Назначение
GET	/metrics	Метрики Prometheus

Все остальные запросы под /v1/..., кроме перечисленных выше трёх GET, проходят через middleware и требуют Authorization: Bearer <api_key> (см. access.md).

Группы маршрутов (соответствие тегам OpenAPI)

Ниже — обзор того, что реализовано в коде (internal/httpapi/routes.go, routes_crud.go). Детали тел, кодов ответов и схем — только в OpenAPI.

Modules

• GET /v1/modules, GET /v1/modules/{module_id}
• POST /v1/modules, PATCH /v1/modules/{module_id}, DELETE /v1/modules/{module_id}
• GET|POST|PATCH|DELETE для .../cdn-sources, .../as-entries, .../domain-entries, .../ip-range-entries
• POST /v1/modules/{module_id}/refresh
• GET /v1/router-lists/catalog — агрегированный каталог модулей/entries/communities

Lookup

• GET /v1/lookup?q= — быстрая проверка IP или FQDN в списках (viewer+).
  • Слой entry: IP_RANGES (CIDR.Contains) / DOMAINS (нормализованный FQDN).
  • Слой snapshot: материализованные module_prefix_snapshot (для IP — Contains по всем модулям; для домена — source=domain у matched DOMAINS-модулей).
  • В каждом матче — community (community_id / значение / title).
  • Live DoH не выполняется. Контракт: OpenAPI lookupMembership.

DoH profiles

• GET|POST /v1/doh-profiles
• GET|PATCH|DELETE /v1/doh-profiles/{id}

Communities

• GET|POST /v1/communities
• GET|PATCH|DELETE /v1/communities/{id}

API keys

• GET /v1/auth/session — tenant и роль текущего ключа
• GET|POST /v1/api-keys — список и создание (operator)
• GET|PATCH|DELETE /v1/api-keys/{id}, POST /v1/api-keys/{id}/rotate

Peers

• GET /v1/peers, POST /v1/peers
• GET|PATCH|DELETE /v1/peers/{id}
• Для POST|PATCH|DELETE peer запускается быстрый job peer_reconcile (без module ingest/сбора префиксов); после него автоматически ставится apply на спикеры.

Speakers

• GET /v1/speakers, POST /v1/speakers
• GET|PATCH /v1/speakers/{speaker_id} (в коде идентификатор в пути — speaker_id; в части маршрутов apply используется {id} — смотрите OpenAPI и реализацию)

Уточнение по коду: для apply на одном спикере зарегистрирован маршрут POST /speakers/{id}/apply внутри v1 mux → POST /v1/speakers/{id}/apply.

Revisions

• GET /v1/revisions, GET /v1/revisions/{revision_id}
• GET /v1/revisions/{revision_id}/prefixes
• GET /v1/revisions/{revision_id}/preview
• GET /v1/revisions/{revision_a}/diff/{revision_b}
• POST /v1/revisions/{revision_id}/rollback

Deploy и BIRD

• POST /v1/apply
• POST /v1/speakers/{id}/apply
• POST /v1/bird/reload

Jobs

• GET /v1/jobs, GET /v1/jobs/{job_id}
• POST /v1/jobs/{job_id}/cancel

Node (роль node)

• GET /v1/speakers/{speaker_id}/revisions/latest
• GET /v1/speakers/{speaker_id}/bundle/{revision_id}
• POST /v1/nodes/enroll

Settings

• GET /v1/settings, PATCH /v1/settings — tenant KV (global_settings): BIRD, revision_retention_minutes, runtime_logs_* (автоочистка FS), произвольные ключи. Чтение — viewer+; PATCH — operator+.

RuntimeLogs

Файловые логи Docker-сервисов (sidecar stack-runtime-logs). FS API только в процессе evobgp-all при EVOBGP_SERVICE=evobgp-all и EVOBGP_RUNTIME_LOGS_DIR (см. access.md). Иначе GET/DELETE по файлам → 503 (runtime_logs_unavailable).

Метод	Путь	Роль	Назначение
GET	/v1/runtime-logs/files	viewer+	Список *.log (имя, размер, mtime)
GET	/v1/runtime-logs/files/{filename}	viewer+	Хвост файла (?lines=, ?bytes=, ?grep=)
DELETE	/v1/runtime-logs/files/{filename}	operator+	Синхронная очистка (?mode=truncate|delete, default truncate); max 512 MiB
GET	/v1/runtime-logs/cleanup-audit	viewer+	Пагинированный audit очистки (cursor, limit); без FS volume
GET	/v1/runtime-logs/auto-estimate	operator+	Файлы выше порога из tenant settings
POST	/v1/runtime-logs/auto-run	operator+	Немедленный прогон (?dry_run=true); audit с actor_prefix=auto:scheduler

{filename} — только basename, паттерн ^[a-z0-9][a-z0-9_.-]*\.log$. Очистка пишет строку в таблицу runtime_log_cleanup_audit (миграция 000026).

CRUD audit (/v1/audit)

Локальный журнал изменений CRUD (modules, peers, settings, API keys, …). Миграция 000030_audit_log. Чтение — bgp:monitoring:read (viewer+).

Метод	Путь	Роль	Назначение
GET	/v1/audit	viewer+	Пагинированный audit (cursor, limit, опционально action, severity)

При AUTH_PORTAL_URL + AUTH_AUDIT_INGEST_SECRET каждая запись дополнительно отправляется в auth-portal (POST /api/v1/ingest/audit, source_app=bgp).

Соглашения из OpenAPI

• Ошибки в стиле RFC 9457 (application/problem+json): type, title, status, detail, и т.д.
• Пагинация списков: query-параметры cursor, limit; в ответе часто items, next_cursor, has_more.
• Заголовок Idempotency-Key для идемпотентных мутаций (рекомендации — в описаниях операций в OpenAPI).
• Заголовок X-Tenant-Id описан в спецификации для супер-ролей; в текущей реализации Go tenant берётся только из API-ключа, заголовок в обработчиках не переключает контекст (см. access.md).

Как смотреть документацию API

• Статическая страница Redoc: openapi.html (инструкции для Gitea и пересборки — OPENAPI-GITEA.md).
• Пересборка после правок YAML (из корня репозитория, PowerShell):

.\scripts\build-openapi-html.ps1

Примеры вызовов

PowerShell, список модулей (подставьте свой токен и URL):

$base = "http://localhost:8080"
$token = "opkey"
$h = @{ Authorization = "Bearer $token" }
Invoke-RestMethod -Uri "$base/v1/modules" -Headers $h

Эквивалент с curl (если установлен):

curl -s -H "Authorization: Bearer opkey" http://localhost:8080/v1/modules

CORS для браузерных клиентов настраивается переменной EVOBGP_CORS_ORIGINS на стороне API.

Связанные документы

• access.md — ключи и роли.
• overview.md — продуктовые возможности.