--- status: Proposed date: 2026-10-11 decision-makers: - Владелец проекта supersedes: [] superseded-by: null --- # ADR-0001: Нейминг API-путей и маршрутизация сервисов через Caddy ## Контекст и проблема На платформе PLBA будет работать несколько сервисов с одинаковыми шаблонами API-путей. PLBA предоставляет общие endpoints управления приложением, а сервисы должны иметь возможность добавлять собственные endpoints в тот же HTTP API и listener. Фронтенду также нужно однозначно выбирать сервис при вызове API. Существующие endpoints `/health`, `/runtime/start`, `/runtime/stop` и `/runtime/status` не содержат версии API. Внешний ingress платформы построен на Caddy с `caddy-docker-proxy`. ## Факторы решения - Все endpoints конкретного сервиса должны находиться в одном версионируемом пространстве путей. - Правило версионирования применяется к endpoints PLBA и к endpoints, добавленным приложением. - Сервисы должны использовать одинаковые внутренние пути независимо от имени сервиса на платформе. - Внешний запрос должен однозначно маршрутизироваться к нужному сервису через Caddy. - PLBA не запускает отдельный HTTP listener; control- и прикладные endpoints обслуживаются через общий listener сервиса. ## Рассмотренные варианты - **Включать имя сервиса во внутренние пути** — например, `/{service-name}/api/v1/orders`. Маршрут явно различает сервисы, но связывает путь приложения с его именем и конфигурацией размещения. - **Добавлять имя сервиса на ingress** — внешний путь имеет вид `/{service-name}/api/v1/orders`, а Caddy выбирает upstream и удаляет `/{service-name}` перед передачей запроса. Внутренний путь сервиса остаётся `/api/v1/orders`. ## Решение Предлагается принять второй вариант. Путь endpoint внутри сервиса начинается с `/api/v{version}/...`, где версия задаётся сегментом пути, например `v1`. Это правило распространяется на все endpoints сервиса, включая endpoints PLBA. В версии `v1` пути PLBA будут такими: - `GET /api/v1/health` - `POST /api/v1/runtime/start` - `POST /api/v1/runtime/stop` - `GET /api/v1/runtime/status` Внешний путь фронтенда начинается с `/{service-name}/api/v{version}/...`. `service-name` — стабильный slug сервиса, настроенный на ingress. Caddy направляет запрос соответствующему upstream и удаляет service-префикс. Приложение получает запрос уже по внутреннему пути `/api/v{version}/...`. PLBA предоставляет общую точку маршрутизации для своих endpoints и endpoints, зарегистрированных приложением. Приложение не создаёт для прикладных endpoints параллельный HTTP listener. ## Последствия - Положительные: сервисы сохраняют единый набор путей; имя размещённого сервиса остаётся настройкой ingress; новые версии API можно публиковать отдельными путями. - Отрицательные или компромиссы: Caddy должен иметь маршрут для каждого публичного service-prefix и корректно удалять его перед проксированием. - Существующие клиенты, прямые вызовы сервисов и health checks нужно перевести на версионированные внутренние пути. - Если приложение формирует абсолютные ссылки на свои endpoints, оно должно учитывать внешний публичный префикс или получать публичный base URL из конфигурации. ## Связанные решения - Нет.