# 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}`

### Peers

- `GET /v1/peers`, `POST /v1/peers`
- `GET|PATCH|DELETE /v1/peers/{id}`

### 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](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) — продуктовые возможности.