Versioning and compatibility
Three version tracks operate independently and conflating them is a common
mistake.
| Track | Mechanism | Contract |
|---|---|---|
| Product | Semantic versioning on the quantumtouch-bng and quantumtouch-core packages |
Ordinary release versioning |
| API path | /api/bng/analytics/v1/* |
The only versioned path prefix — the customer-facing compatibility boundary |
| Metric registry | A registry-wide version plus a per-metric since_version |
Semantic versioning inside the registry, so a consumer can pin against it |
The unversioned /api/bng/* operator routes are an internal contract between the
QuantumTouch UI and its backend, shipped together and evolving together. They are
documented here because integrators legitimately use them and because parity with
the UI is a design commitment — but the formal compatibility promise attaches to
the versioned analytics prefix and to the metric registry.
Response evolution is additive. New fields are added to existing payloads on
the standing assumption that consumers ignore keys they do not recognise. An
integration should parse defensively and not fail on unknown fields.
The PromQL passthrough is deliberately not versioned by QuantumTouch — it
inherits Prometheus's own v1, because verbatim mirroring of the upstream
contract is the entire point of the surface.
Data formats carry their own schema versions independent of the software version:
the key store and the snapshot format each version separately, with migration
applied transparently on read.