- Added endpoints for managing API keys, including creation, retrieval, updating, and revocation.
- Introduced a new Auth session endpoint to retrieve current tenant and role information.
- Updated the authentication middleware to support API key-based authentication and track last used timestamps.
- Enhanced documentation to reflect new API key functionalities and usage guidelines.
- Improved logging for demo authentication scenarios.

2026-05-21 11:26:17 +07:00

5.9 KiB

Raw Blame History

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

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

Соглашения из 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 — продуктовые возможности.

5.9 KiB Raw Blame History Unescape Escape