DenozordecandCursor
a0f78a3d21
Обновлены разделы документации для управления файловыми логами, включая новые эндпоинты и параметры. Добавлены описания для вкладки «Файловые логи» в интерфейсе мониторинга и обновлены настройки tenant. Улучшен доступ к логам через API и интерфейс пользователя. Co-authored-by: Cursor <cursoragent@cursor.com>
147 lines
7.1 KiB
Markdown
147 lines
7.1 KiB
Markdown
# REST API: обзор и ссылки
|
||
|
||
Полный контракт запросов и ответов описан в **[openapi.yaml](openapi.yaml)** (OpenAPI 3.1). Этот файл — **источник правды**. Краткий контекст и ранние таблицы — в [evobgp-api-sketches.md](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](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` — tenant KV (`global_settings`): BIRD, `revision_retention_minutes`, произвольные ключи. Чтение — viewer+; `PATCH` — operator+.
|
||
|
||
### RuntimeLogs
|
||
|
||
Файловые логи Docker-сервисов (sidecar `stack-runtime-logs`). FS API **только** в процессе **`evobgp-all`** при `EVOBGP_SERVICE=evobgp-all` и `EVOBGP_RUNTIME_LOGS_DIR` (см. [access.md](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`) |
|
||
|
||
`{filename}` — только basename, паттерн `^[a-z0-9][a-z0-9_.-]*\.log$`. Очистка пишет строку в таблицу `runtime_log_cleanup_audit` (миграция `000026`).
|
||
|
||
## Соглашения из 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](access.md)).
|
||
|
||
## Как смотреть документацию API
|
||
|
||
- Статическая страница Redoc: [openapi.html](openapi.html) (инструкции для Gitea и пересборки — [OPENAPI-GITEA.md](OPENAPI-GITEA.md)).
|
||
- Пересборка после правок YAML (из корня репозитория, PowerShell):
|
||
|
||
```powershell
|
||
.\scripts\build-openapi-html.ps1
|
||
```
|
||
|
||
## Примеры вызовов
|
||
|
||
PowerShell, список модулей (подставьте свой токен и URL):
|
||
|
||
```powershell
|
||
$base = "http://localhost:8080"
|
||
$token = "opkey"
|
||
$h = @{ Authorization = "Bearer $token" }
|
||
Invoke-RestMethod -Uri "$base/v1/modules" -Headers $h
|
||
```
|
||
|
||
Эквивалент с `curl` (если установлен):
|
||
|
||
```text
|
||
curl -s -H "Authorization: Bearer opkey" http://localhost:8080/v1/modules
|
||
```
|
||
|
||
CORS для браузерных клиентов настраивается переменной **`EVOBGP_CORS_ORIGINS`** на стороне API.
|
||
|
||
## Связанные документы
|
||
|
||
- [access.md](access.md) — ключи и роли.
|
||
- [overview.md](overview.md) — продуктовые возможности.
|