EvoBGP/docs/router-lists-ui-integration.md

Интеграция router-lists-ui с EvoBGP API

Документ описывает подключение разделов Домены, IP-диапазоны, AS, Community из проекта router-lists-ui напрямую к EvoBGP API (/v1).

Источник правды по контракту: openapi.yaml.

1. Базовые требования

• Base URL API: https://<evobgp-host>/v1
• Аутентификация: Authorization: Bearer <api_key>
• CORS на стороне EvoBGP: переменная EVOBGP_CORS_ORIGINS
• Роли:
  • чтение: viewer+
  • изменение данных: editor+
  • apply/деплой: operator

2. Маппинг legacy -> EvoBGP

Раздел UI	Legacy endpoint	EvoBGP endpoint
Домены	/api/domains-new	/v1/modules?type=DOMAINS + /v1/modules/{module_id}/domain-entries
IP-диапазоны	/api/ip-ranges	/v1/modules?type=IP_RANGES + /v1/modules/{module_id}/ip-range-entries
AS	/api/asns	/v1/modules?type=AS_PREFIXES + /v1/modules/{module_id}/as-entries
Community	/api/communities	/v1/communities

Для упрощённой интеграции доступен агрегированный endpoint: GET /v1/router-lists/catalog (модули + entries + communities в одном ответе).

3. Маппинг полей

Legacy модель	EvoBGP модель	Комментарий
{ domain, community }	DomainEntry { fqdn, community_id }	community в UI резолвится в community_id через /v1/communities
{ ipRange, community }	IpRangeEntry { prefix, community_id }	Для IP_RANGES community_id обязателен
{ domain, type } (AS)	AsEntry { asn, community_id }	domain legacy = ASN
{ value, name } (Community dict)	BgpCommunity { community, title }	value -> community, name -> title

4. Алгоритм работы по разделам

4.1 Домены / IP / AS (общая схема)

1. Найти модуль нужного типа через GET /v1/modules?type=....
2. Если модуль отсутствует, создать через POST /v1/modules.
3. Загрузить entries:
   • домены: GET /v1/modules/{module_id}/domain-entries
   • IP: GET /v1/modules/{module_id}/ip-range-entries
   • AS: GET /v1/modules/{module_id}/as-entries
4. При сохранении:
   • удалить отсутствующие записи (DELETE .../{entry_id})
   • обновить изменённые (PATCH .../{entry_id})
   • добавить новые (POST ...)

4.2 Community

1. Получить список: GET /v1/communities
2. Для сохранения diff:
   • новые -> POST /v1/communities
   • изменённые -> PATCH /v1/communities/{id}
   • удалённые -> DELETE /v1/communities/{id}

5. Разрешение community

• Перед работой с entries загрузить /v1/communities.
• Основной путь: сопоставление по id.
• Для UI-формы использовать значение community (например, 65001:120) и перед записью преобразовывать в community_id.
• Если community не найдена:
  • для IP_RANGES считать ошибкой валидации;
  • для DOMAINS и AS_PREFIXES можно передать null только если это допускается бизнес-логикой.

6. Пагинация и ошибки

• Списки используют cursor + limit.
• Формат ошибок: application/problem+json (RFC 9457).
• Базовая обработка:
  • 401 — неверный/отсутствующий токен
  • 403 — недостаточно прав
  • 404 — ресурс не найден
  • 422 — ошибка валидации

7. Примеры (PowerShell)

$base = "http://localhost:8080/v1"
$token = "YOUR_API_KEY"
$h = @{ Authorization = "Bearer $token" }

# 1) Найти модуль DOMAINS
$modules = Invoke-RestMethod -Uri "$base/modules?type=DOMAINS&limit=50" -Headers $h
$moduleId = $modules.items[0].id

# 2) Прочитать домены
Invoke-RestMethod -Uri "$base/modules/$moduleId/domain-entries?limit=100" -Headers $h

# Создать community
$body = @{
  community = "65001:120"
  title     = "Video"
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "$base/communities" -Headers $h -ContentType "application/json" -Body $body

8. Настройки router-lists-ui для прямой интеграции

Рекомендуемые переменные frontend:

• VITE_EVOBGP_API_URL (по умолчанию /v1)
• VITE_EVOBGP_API_TOKEN (опционально; либо хранить токен в localStorage как evobgp_api_token)

Для dev-прокси Vite добавить маршрут /v1 -> http://localhost:8080.

9. Контрольный список интеграции

• Домены: list/create/update/delete работают через /v1/modules/{id}/domain-entries
• IP-диапазоны: list/create/update/delete работают через /v1/modules/{id}/ip-range-entries
• AS: list/create/update/delete работают через /v1/modules/{id}/as-entries
• Community: CRUD работает через /v1/communities
• ошибки problem+json корректно отображаются в UI