diff --git a/docs/OPENAPI-GITEA.md b/docs/OPENAPI-GITEA.md index e2694c5..ddd7054 100644 --- a/docs/OPENAPI-GITEA.md +++ b/docs/OPENAPI-GITEA.md @@ -1,6 +1,6 @@ # Как смотреть API-документацию (Gitea без встроенного OpenAPI) -В веб-интерфейсе Gitea файлы из репозитория показываются **как исходный текст** (в т.ч. HTML) — это нормально: страница в браузере **не выполняется** из просмотра кода. +В веб-интерфейсе Gitea файлы из репозитория показываются **как исходный текст** (в т.ч. HTML) - это нормально: страница в браузере **не выполняется** из просмотра кода. ## Самый простой способ @@ -31,4 +31,4 @@ Или вручную: `npx @redocly/cli@1 build-docs docs/openapi.yaml -o docs/openapi.html`, затем встроить `redoc.standalone.js` по аналогии со скриптом. -Источник правды по контракту API — **`docs/openapi.yaml`** (OpenAPI 3.1). +Источник правды по контракту API - **`docs/openapi.yaml`** (OpenAPI 3.1). diff --git a/docs/evobgp-api-sketches.md b/docs/evobgp-api-sketches.md index 86c8496..3cc05d2 100644 --- a/docs/evobgp-api-sketches.md +++ b/docs/evobgp-api-sketches.md @@ -1,6 +1,6 @@ -# EvoBGP — наброски HTTP API +# EvoBGP - наброски HTTP API -**Статус:** черновик для согласования; не спецификация реализации. Базовый префикс: **`/v1`**. Модель данных и термины — в архитектурном плане (модули, `bgp_speaker`, `config_revision`, `job_audit`). +**Статус:** черновик для согласования; не спецификация реализации. Базовый префикс: **`/v1`**. Модель данных и термины - в архитектурном плане (модули, `bgp_speaker`, `config_revision`, `job_audit`). --- @@ -10,13 +10,13 @@ |------|---------------------| | **Аутентификация** | Заголовок `Authorization: Bearer ` или mTLS на edge; ключи привязаны к tenant и роли. | | **Multi-tenant** | Все сущности в скоупе tenant: либо из ключа, либо явный префикс `X-Tenant-Id` (только для супер-ролей). | -| **Идентификаторы** | UUID v7 или ULID в URL; в JSON — строки. | +| **Идентификаторы** | UUID v7 или ULID в URL; в JSON - строки. | | **Время** | ISO 8601 UTC (`2026-04-03T12:00:00Z`). | | **Ошибки** | Тело `application/problem+json` (RFC 9457): `type`, `title`, `status`, `detail`, `instance`, опционально `errors[]` по полям. | | **Идемпотентность** | Для мутаций, создающих задачи или побочные эффекты: заголовок `Idempotency-Key` (опционально обязателен для `POST` apply/refresh). | | **Пагинация** | `?cursor=&limit=50` (cursor-based); ответ: `items`, `next_cursor`, `has_more`. | | **Асинхронные операции** | `202 Accepted`, заголовок `Location: /v1/jobs/{job_id}`; тело `{ "job_id", "status": "queued" }`. | -| **Версионирование** | Несовместимые изменения — новый префикс `/v2`. | +| **Версионирование** | Несовместимые изменения - новый префикс `/v2`. | --- @@ -34,7 +34,7 @@ ### Связь с продуктом -**ASN / CDN / DOMAINS / IP-диапазоны** в продуктовой формулировке — это **четыре вида модулей**. Поле **`type`** в `POST /v1/modules` выбирает вид: `AS_PREFIXES`, `CDN_CIDRS`, `DOMAINS` или **`IP_RANGES`**. Дочерние ресурсы: **`as-entries`**, **`cdn-sources`**, **`domain-entries`** — как раньше; **`ip-range-entries`** — статические **CIDR + `community_id`** (без ASN и без URL). **`module_id`** в пути — идентификатор **конкретного экземпляра** модуля, а не имя типа. +**ASN / CDN / DOMAINS / IP-диапазоны** в продуктовой формулировке - это **четыре вида модулей**. Поле **`type`** в `POST /v1/modules` выбирает вид: `AS_PREFIXES`, `CDN_CIDRS`, `DOMAINS` или **`IP_RANGES`**. Дочерние ресурсы: **`as-entries`**, **`cdn-sources`**, **`domain-entries`** - как раньше; **`ip-range-entries`** - статические **CIDR + `community_id`** (без ASN и без URL). **`module_id`** в пути - идентификатор **конкретного экземпляра** модуля, а не имя типа. Типы: `AS_PREFIXES`, `CDN_CIDRS`, `DOMAINS`, `IP_RANGES` (как в плане). @@ -44,7 +44,7 @@ | `POST` | `/v1/modules` | Создать модуль. | | `GET` | `/v1/modules/{module_id}` | Детали модуля. | | `PATCH` | `/v1/modules/{module_id}` | Частичное обновление (расписание, DoH, приоритет, `enabled`). | -| `DELETE` | `/v1/modules/{module_id}` | Мягкое удаление или `enabled=false` — зафиксировать в плане реализации. | +| `DELETE` | `/v1/modules/{module_id}` | Мягкое удаление или `enabled=false` - зафиксировать в плане реализации. | **CDN-источники модуля** @@ -81,7 +81,7 @@ | Метод | Путь | Описание | |-------|------|----------| -| `POST` | `/v1/modules/{module_id}/refresh` | Запуск ingest для модуля (CDN / DoH / AS по типу). Для **`IP_RANGES`** обычно **не требуется** (данные только в БД); возможен **`204`** / no-op или отказ **`400`**, если тип не поддерживает refresh — зафиксировать в реализации. | +| `POST` | `/v1/modules/{module_id}/refresh` | Запуск ingest для модуля (CDN / DoH / AS по типу). Для **`IP_RANGES`** обычно **не требуется** (данные только в БД); возможен **`204`** / no-op или отказ **`400`**, если тип не поддерживает refresh - зафиксировать в реализации. | **Пример тела создания модуля (набросок)** @@ -107,7 +107,7 @@ | Метод | Путь | Описание | |-------|------|----------| | `GET` | `/v1/doh-profiles` | Список. | -| `POST` | `/v1/doh-profiles` | Создать (URL, таймауты; секрет — ссылка на vault id или отдельный `POST .../secret`). | +| `POST` | `/v1/doh-profiles` | Создать (URL, таймауты; секрет - ссылка на vault id или отдельный `POST .../secret`). | | `GET` | `/v1/doh-profiles/{id}` | Детали (без раскрытия секрета). | | `PATCH` | `/v1/doh-profiles/{id}` | Обновить. | | `DELETE` | `/v1/doh-profiles/{id}` | Удалить, если не используется модулями. | @@ -163,7 +163,7 @@ | Метод | Путь | Описание | |-------|------|----------| -| `GET` | `/v1/revisions/{a}/diff/{b}` | Diff префиксов / метаданных (формат — зафиксировать: JSON patch или табличный). | +| `GET` | `/v1/revisions/{a}/diff/{b}` | Diff префиксов / метаданных (формат - зафиксировать: JSON patch или табличный). | --- @@ -221,7 +221,7 @@ |-------|------|----------| | `GET` | `/v1/speakers/{speaker_id}/revisions/latest` | Указатель на последнюю опубликованную ревизию для ноды. | | `GET` | `/v1/speakers/{speaker_id}/bundle/{revision_id}` | Скачивание подписанного бандла (архив + `manifest.json` + подпись). | -| `POST` | `/v1/nodes/enroll` | Регистрация ноды (обмен ключами, привязка к `speaker_id`) — детали протокола отдельно. | +| `POST` | `/v1/nodes/enroll` | Регистрация ноды (обмен ключами, привязка к `speaker_id`) - детали протокола отдельно. | Заголовки для бандла: `Content-Type: application/octet-stream` или multipart; контроль целостности по `manifest` (SHA-256) и подписи (например Ed25519). @@ -264,7 +264,7 @@ |------------|----------------| | REST, jobs | §1, §10 | | refresh, apply, rollback, preview, `IP_RANGES` | §3, §8, §9 | -| peers, speakers, communities, DoH | §4–§7 | +| peers, speakers, communities, DoH | §4 - §7 | | bundle API, нода | §11 | Файл плана: `.cursor/plans/evobgp_архитектура_0e73ef02.plan.md` (§6 REST API). diff --git a/docs/openapi.html b/docs/openapi.html index 2d20123..5cd7b31 100644 --- a/docs/openapi.html +++ b/docs/openapi.html @@ -2275,15 +2275,15 @@ data-styled.g138[id="sc-iJQrDi"]{content:"gtHWGb,"}/*!sc*/ -231.5279,231.248 -231.873,231.248 -0.3451,0 -104.688, -104.0616 -231.873,-231.248 z " fill="currentColor">

EvoBGP Control Plane API (0.1.0)

Download OpenAPI specification:

License: LicenseRef-Proprietary

REST API управления префиксами, модулями ingest, ревизиями конфигурации BIRD и задачами (async jobs).

-

Соглашения: префикс /v1; идентификаторы — UUID v7 или ULID (строки); время — ISO 8601 UTC. -Ошибки — application/problem+json (RFC 9457). -Пагинация списков — cursor + limit; ответ содержит items, next_cursor, has_more.

+

Соглашения: префикс /v1; идентификаторы - UUID v7 или ULID (строки); время - ISO 8601 UTC. +Ошибки - application/problem+json (RFC 9457). +Пагинация списков - cursor + limit; ответ содержит items, next_cursor, has_more.

Роли (матрица доступа): viewer, editor, operator, node. Нода использует отдельные пути и ключ с ролью node.

Заголовок X-Tenant-Id допускается только для супер-ролей (явный tenant); иначе tenant берётся из API-ключа.

Черновик и контекст API

System

Ошибка (см. тело Problem).

Response samples

Content type
application/json
{
  • "api_version": "string",
  • "git_sha": "string",
  • "build_time": "2019-08-24T14:15:22Z"
}

Modules

Экземпляры модулей префиксов (AS, CDN, домены, статические IP-диапазоны) и вложенные записи. Чтение — viewer+; изменение — editor+.

+
https://api.example.com/v1/version

Response samples

Content type
application/json
{
  • "api_version": "string",
  • "git_sha": "string",
  • "build_time": "2019-08-24T14:15:22Z"
}

Modules

Экземпляры модулей префиксов (AS, CDN, домены, статические IP-диапазоны) и вложенные записи. Чтение - viewer+; изменение - editor+.

Список модулей

Модули tenant с опциональными фильтрами по типу и флагу enabled.

Authorizations:
bearerAuth
query Parameters
cursor
string

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "has_more": true
}

Создать модуль

Создаёт экземпляр модуля. Поле type задаёт вид (AS_PREFIXES, CDN_CIDRS, DOMAINS, IP_RANGES). -module_id в других путях — идентификатор экземпляра, не имя типа.

+module_id в других путях - идентификатор экземпляра, не имя типа.

Authorizations:
bearerAuth
header Parameters
X-Tenant-Id
string (ResourceId) ^[0-9A-Za-z_-]{20,36}$
Examples: 01JQXYZABCDEFGHIJKLMNOPQRS

Явный tenant (только супер-роли). Без заголовка tenant определяется по ключу.

Idempotency-Key
string <= 256 characters

Ошибка (см. тело Problem).

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "priority": 0,
  • "doh_profile_id": "string",
  • "refresh_interval_sec": 0,
  • "cron_expr": "string",
  • "default_community_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "01JQXYZABCDEFGHIJKLMNOPQRS",
  • "type": "AS_PREFIXES",
  • "name": "string",
  • "enabled": true,
  • "priority": 0,
  • "doh_profile_id": "string",
  • "refresh_interval_sec": 0,
  • "cron_expr": "string",
  • "default_community_id": "string"
}

Удалить модуль

Мягкое удаление или перевод в enabled=false — конкретное поведение задаётся реализацией.

+
https://api.example.com/v1/modules/{module_id}

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "priority": 0,
  • "doh_profile_id": "string",
  • "refresh_interval_sec": 0,
  • "cron_expr": "string",
  • "default_community_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "01JQXYZABCDEFGHIJKLMNOPQRS",
  • "type": "AS_PREFIXES",
  • "name": "string",
  • "enabled": true,
  • "priority": 0,
  • "doh_profile_id": "string",
  • "refresh_interval_sec": 0,
  • "cron_expr": "string",
  • "default_community_id": "string"
}

Удалить модуль

Мягкое удаление или перевод в enabled=false - конкретное поведение задаётся реализацией.

Authorizations:
bearerAuth
path Parameters
module_id
required
string (ResourceId) ^[0-9A-Za-z_-]{20,36}$
Examples: 01JQXYZABCDEFGHIJKLMNOPQRS

UUID v7 или ULID.

header Parameters
X-Tenant-Id
string (ResourceId) ^[0-9A-Za-z_-]{20,36}$
Examples: 01JQXYZABCDEFGHIJKLMNOPQRS

Response samples

Content type
application/problem+json
{
  • "type": "../dictionary",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "../dictionary",
  • "errors": [
    ]
}

Запустить ingest

Запуск обновления данных модуля (CDN / DoH / AS в зависимости от типа). -Для IP_RANGES данные обычно только в БД: сервер может вернуть 204 (no-op) или 400, если refresh не поддерживается — поведение фиксируется в реализации. +Для IP_RANGES данные обычно только в БД: сервер может вернуть 204 (no-op) или 400, если refresh не поддерживается - поведение фиксируется в реализации. Рекомендуется передавать Idempotency-Key.

Authorizations:
bearerAuth
path Parameters
module_id
required
string (ResourceId) ^[0-9A-Za-z_-]{20,36}$
Examples: 01JQXYZABCDEFGHIJKLMNOPQRS

UUID v7 или ULID.

@@ -2718,8 +2718,8 @@ data-styled.g138[id="sc-iJQrDi"]{content:"gtHWGb,"}/*!sc*/ " class="sc-iKGpAq sc-cCYyou sc-cjERFZ dXXcln fTBBlJ dkmSdy">

Ошибка (см. тело Problem).

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "has_more": true
}

Создать DoH-профиль

URL и таймауты; секрет — через vault id или отдельный вызов установки секрета.

+
https://api.example.com/v1/doh-profiles

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "has_more": true
}

Создать DoH-профиль

URL и таймауты; секрет - через vault id или отдельный вызов установки секрета.

Authorizations:
bearerAuth
header Parameters
X-Tenant-Id
string (ResourceId) ^[0-9A-Za-z_-]{20,36}$
Examples: 01JQXYZABCDEFGHIJKLMNOPQRS

Явный tenant (только супер-роли). Без заголовка tenant определяется по ключу.

Idempotency-Key
string <= 256 characters

UUID v7 или ULID.

header Parameters
X-Tenant-Id
string (ResourceId) ^[0-9A-Za-z_-]{20,36}$
Examples: 01JQXYZABCDEFGHIJKLMNOPQRS

Явный tenant (только супер-роли). Без заголовка tenant определяется по ключу.

-

Responses

Responses

Response samples

Content type
application/json
{
  • "revision_id": "01JQXYZABCDEFGHIJKLMNOPQRS",
  • "published_at": "2019-08-24T14:15:22Z"
}

Скачать подписанный бандл

Архив с manifest.json и подписью (например Ed25519). Целостность по SHA-256 в манифесте. -Content-Type — application/octet-stream или multipart; детали — в реализации.

+Content-Type - application/octet-stream или multipart; детали - в реализации.

Authorizations:
bearerAuth
path Parameters
speaker_id
required
string (ResourceId) ^[0-9A-Za-z_-]{20,36}$
Examples: 01JQXYZABCDEFGHIJKLMNOPQRS

UUID v7 или ULID.

revision_id
required
string (ResourceId) ^[0-9A-Za-z_-]{20,36}$
Examples: 01JQXYZABCDEFGHIJKLMNOPQRS

Ошибка (см. тело Problem).

Request samples

Content type
application/json
{
  • "public_key": "string",
  • "speaker_id": "01JQXYZABCDEFGHIJKLMNOPQRS"
}

Response samples

Content type
application/json
{ }

Settings

Глобальные настройки и feature flags; изменение — только operator.

+
https://api.example.com/v1/nodes/enroll

Request samples

Content type
application/json
{
  • "public_key": "string",
  • "speaker_id": "01JQXYZABCDEFGHIJKLMNOPQRS"
}

Response samples

Content type
application/json
{ }

Settings

Глобальные настройки и feature flags; изменение - только operator.

Получить настройки

KV (лимиты CDN, feature flags и т.д.).

Authorizations:
bearerAuth
header Parameters
X-Tenant-Id
string (ResourceId) ^[0-9A-Za-z_-]{20,36}$
Examples: 01JQXYZABCDEFGHIJKLMNOPQRS

Базовый URL инсталляции (замените на свой)

https://api.example.com/v1/settings

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }