Files
plba_v2/openspec/changes/archive/2026-10-11-versioned-extensible-http-api/proposal.md
T
alex 2f47fc74cf
PLBA package CI / Python tests (push) Successful in 8s
PLBA package CI / Package version increment (push) Skipped
PLBA2-4. Архивация спеки
2026-10-11 11:01:02 +03:00

28 lines
2.1 KiB
Markdown

# Proposal
## Why
`ControlApi` сейчас обслуживает только четыре зашитых в код маршрута, поэтому приложение не может добавить собственные endpoints в общую точку маршрутизации PLBA. Кроме того, текущие пути не соответствуют целевому versioned-префиксу ADR-0001, из-за чего сервисы не имеют единого контракта для внутренних и внешних запросов через Caddy.
## What Changes
- **BREAKING**: перенести встроенные endpoints на `/api/v1/`: `/health`, `/runtime/start`, `/runtime/stop` и `/runtime/status`.
- Добавить расширяемую маршрутизацию, где приложение регистрирует собственные endpoints в том же API и listener, что и endpoints PLBA.
- Требовать путь `/api/v{version}/...` для всех регистрируемых endpoints и поддержать маршруты с параметрами пути.
- Документировать внешний путь `/{service-name}/api/v{version}/...` и проксирование Caddy с удалением service-префикса.
## Capabilities
### New Capabilities
### Modified Capabilities
- `api/http/control-api`: изменить пути встроенных endpoints и расширить общую точку маршрутизации для endpoints приложения.
## Impact
- HTTP API и публичный интерфейс PLBA в `src/plba/http/`.
- Контракт существующих клиентов и проверок health: они должны вызывать новые versioned-пути.
- Документация интеграции, unit/contract проверки HTTP API и `pyproject.toml`.
- ADR-0001 задаёт целевой нейминг и ingress-маршрутизацию; его статус остаётся `Proposed` до явного принятия владельцем решения.