denozord/EvoBGP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 131 Wiki Activity
Files
b7968db4e06efd6c5ba67e801e591c1d77eb924f
EvoBGP/docs/evobgp-api-sketches.md
T

14 KiB
Raw Blame History

EvoBGP - наброски HTTP API

Статус: черновик для согласования; не спецификация реализации. Базовый префикс: /v1. Модель данных и термины - в архитектурном плане (модули, bgp_speaker, config_revision, job_audit).

1. Общие соглашения

Тема Решение (набросок)
Аутентификация Заголовок Authorization: Bearer <api_key> или mTLS на edge; ключи привязаны к tenant и роли.
Multi-tenant Все сущности в скоупе tenant: либо из ключа, либо явный префикс X-Tenant-Id (только для супер-ролей).
Идентификаторы 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=<opaque>&limit=50 (cursor-based); ответ: items, next_cursor, has_more.
Асинхронные операции 202 Accepted, заголовок Location: /v1/jobs/{job_id}; тело { "job_id", "status": "queued" }.
Версионирование Несовместимые изменения - новый префикс /v2.

2. Системные и служебные

Метод Путь Назначение
GET /v1/health Liveness (процесс жив).
GET /v1/ready Readiness (БД, брокер при reference, и т.д.).
GET /v1/version Версия сборки API и control-plane (git_sha, build_time).

3. Модули префиксов (module)

Связь с продуктом

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 (как в плане).

Метод Путь Описание
GET /v1/modules Список модулей tenant (фильтры: ?type=, ?enabled=).
POST /v1/modules Создать модуль.
GET /v1/modules/{module_id} Детали модуля.
PATCH /v1/modules/{module_id} Частичное обновление (расписание, DoH, приоритет, enabled).
DELETE /v1/modules/{module_id} Мягкое удаление или enabled=false - зафиксировать в плане реализации.

CDN-источники модуля

Метод Путь Описание
GET /v1/modules/{module_id}/cdn-sources Список строк CDN.
POST /v1/modules/{module_id}/cdn-sources Добавить источник (URL + source_kind + опционально community_id).
PATCH /v1/modules/{module_id}/cdn-sources/{source_id} URL, source_kind, community_id, свой refresh_interval_sec.
DELETE /v1/modules/{module_id}/cdn-sources/{source_id} Удалить.

Записи AS / домены

Метод Путь Описание
GET /v1/modules/{module_id}/as-entries Список ASN/префиксов.
POST /v1/modules/{module_id}/as-entries Добавить.
PATCH /v1/modules/{module_id}/as-entries/{entry_id} Обновить.
DELETE /v1/modules/{module_id}/as-entries/{entry_id} Удалить.
GET /v1/modules/{module_id}/domain-entries FQDN + community.
POST /v1/modules/{module_id}/domain-entries Добавить.
PATCH /v1/modules/{module_id}/domain-entries/{entry_id} Обновить.
DELETE /v1/modules/{module_id}/domain-entries/{entry_id} Удалить.

Записи IP-диапазонов (только для type: IP_RANGES)

Метод Путь Описание
GET /v1/modules/{module_id}/ip-range-entries Список CIDR + community_id.
POST /v1/modules/{module_id}/ip-range-entries Добавить запись (prefix, community_id).
PATCH /v1/modules/{module_id}/ip-range-entries/{entry_id} Обновить.
DELETE /v1/modules/{module_id}/ip-range-entries/{entry_id} Удалить.

Refresh (ingest)

Метод Путь Описание
POST /v1/modules/{module_id}/refresh Запуск ingest для модуля (CDN / DoH / AS по типу). Для IP_RANGES обычно не требуется (данные только в БД); возможен 204 / no-op или отказ 400, если тип не поддерживает refresh - зафиксировать в реализации.

Пример тела создания модуля (набросок)

{
  "type": "CDN_CIDRS",
  "name": "edge-v4",
  "enabled": true,
  "priority": 10,
  "doh_profile_id": null,
  "refresh_interval_sec": 3600,
  "cron_expr": null,
  "default_community_id": "550e8400-e29b-41d4-a716-446655440000"
}

Пример модуля IP_RANGES (набросок): type: "IP_RANGES", doh_profile_id: null, далее строки через ip-range-entries с полями prefix (например 203.0.113.0/24) и community_id.

4. DoH-профили (doh_profile)

Метод Путь Описание
GET /v1/doh-profiles Список.
POST /v1/doh-profiles Создать (URL, таймауты; секрет - ссылка на vault id или отдельный POST .../secret).
GET /v1/doh-profiles/{id} Детали (без раскрытия секрета).
PATCH /v1/doh-profiles/{id} Обновить.
DELETE /v1/doh-profiles/{id} Удалить, если не используется модулями.

5. BGP community (bgp_community)

Метод Путь Описание
GET /v1/communities Список справочника.
POST /v1/communities Создать.
GET /v1/communities/{id} Детали.
PATCH /v1/communities/{id} Обновить.
DELETE /v1/communities/{id} Удалить при отсутствии ссылок.

6. Пиры (bgp_peer)

Метод Путь Описание
GET /v1/peers Список (?speaker_id=, пагинация).
POST /v1/peers Создать пира.
GET /v1/peers/{id} Детали.
PATCH /v1/peers/{id} Политики, neighbor, ASN, привязка к bgp_speaker_id или null = все спикеры.
DELETE /v1/peers/{id} Удалить / отключить.

7. Спикеры BIRD (bgp_speaker)

Метод Путь Описание
GET /v1/speakers Список (master / replica, endpoint).
POST /v1/speakers Зарегистрировать спикер (реплика, canary).
GET /v1/speakers/{id} Детали + last_applied_revision_id.
PATCH /v1/speakers/{id} Метаданные, endpoint.

8. Ревизии конфигурации (config_revision)

Метод Путь Описание
GET /v1/revisions История ревизий (?module_id=, ?limit=).
GET /v1/revisions/{revision_id} Метаданные: хэш, родитель, время, артефакты.
GET /v1/revisions/{revision_id}/prefixes Материализованный снимок префиксов (пагинация).
GET /v1/revisions/{revision_id}/preview Превью фрагментов BIRD (read-only, без apply).
POST /v1/revisions/{revision_id}/rollback Создать новую ревизию с содержимым отката; часто 202.

Сравнение ревизий (набросок)

Метод Путь Описание
GET /v1/revisions/{a}/diff/{b} Diff префиксов / метаданных (формат - зафиксировать: JSON patch или табличный).

9. Применение конфигурации (deploy / BIRD)

Метод Путь Описание
POST /v1/apply Применить текущую целевую ревизию на всех спикерах (или по политике по умолчанию). 202.
POST /v1/speakers/{id}/apply Применить на одном спикере (canary). 202.
POST /v1/bird/reload Опционально: явный мягкий reload политики (если отделён от apply); иначе часть apply.

Тело POST /v1/apply (набросок, опционально)

{
  "revision_id": "01JQXYZ...",
  "strategy": "all_speakers",
  "dry_run": false
}

10. Задачи (job_audit)

Метод Путь Описание
GET /v1/jobs Список задач (?status=, ?kind=, cursor).
GET /v1/jobs/{job_id} Статус, прогресс, ошибка, связанные сущности.
POST /v1/jobs/{job_id}/cancel Запрос отмены (best-effort).

Пример ответа GET /v1/jobs/{id}

{
  "job_id": "01JQXYZ...",
  "kind": "module_refresh",
  "status": "running",
  "idempotency_key": "client-abc-123",
  "created_at": "2026-04-03T10:00:00Z",
  "started_at": "2026-04-03T10:00:01Z",
  "finished_at": null,
  "error": null,
  "meta": { "module_id": "01JQM..." }
}

11. Реплики (evobgp-node): бандлы

Вызываются нодой с отдельным ключом / mTLS (роль node).

Метод Путь Описание
GET /v1/speakers/{speaker_id}/revisions/latest Указатель на последнюю опубликованную ревизию для ноды.
GET /v1/speakers/{speaker_id}/bundle/{revision_id} Скачивание подписанного бандла (архив + manifest.json + подпись).
POST /v1/nodes/enroll Регистрация ноды (обмен ключами, привязка к speaker_id) - детали протокола отдельно.

Заголовки для бандла: Content-Type: application/octet-stream или multipart; контроль целостности по manifest (SHA-256) и подписи (например Ed25519).

12. Глобальные настройки и операторские флаги (опционально)

Метод Путь Описание
GET /v1/settings KV вроде global_settings (лимиты CDN, feature flags).
PATCH /v1/settings Частичное обновление (только роль operator).

13. Набросок матрицы прав (роли)

Ресурс viewer editor operator node
GET модули, ревизии, peers да да да нет*
PATCH модули, peers нет да да нет
apply, rollback нет нет да нет
bundle / enroll нет нет нет да

*Нода не ходит в общий CRUD; только §11.

14. Что вынести в следующую итерацию

  • Полная OpenAPI 3.1 схема (openapi.yaml) из этого документа.
  • Webhooks: POST на URL клиента по завершении job (опционально).
  • SSE/WebSocket для стрима статуса долгих jobs.
  • Rate limits по ключу и по tenant в ответах (RateLimit-* заголовки).

15. Связь с архитектурным планом

Тема плана Раздел здесь
REST, jobs §1, §10
refresh, apply, rollback, preview, IP_RANGES §3, §8, §9
peers, speakers, communities, DoH §4 - §7
bundle API, нода §11

Файл плана: .cursor/plans/evobgp_архитектура_0e73ef02.plan.md (§7 REST API).

Reference in New Issue View Git Blame Copy Permalink