QuantumTouch Operational API — Theory of Operations
The BlueDot BNG exposes two northbound interfaces, and the distinction between
them is the organising idea of this document.
The first is the BNG Telemetry API — the controller's own REST surface,
described in the companion BNG Telemetry API Theory of Operations. It answers
questions about subscribers and traffic: who is connected, what plan they
hold, how many octets they passed in each QoS colour, how full the address pools
are. It is deliberately raw. It stores no history, computes no trends, and
returns cumulative counters and current state for a consumer to interpret.
The second is the Touch Operational API, the subject of this document. It is
served by QuantumTouch, BlueDot's operational layer for the BNG, and it answers a
different class of question: is this node healthy, what changed, who changed
it, what was it like before, and what will it be like if I change it again.
It is the interface an automation engineer uses to operate a BNG — not to read
subscriber counters, but to poll composed health, retain and query time series,
manage an event lifecycle with acknowledgement, read a merged audit timeline
across four independent sources, capture and restore configuration snapshots,
and administer the credentials that gate all of it.
Three properties define the interface and are worth stating before any endpoint
is described.
It is the same interface the QuantumTouch web UI uses. The QuantumTouch SPA
is an ordinary client of the endpoints in this document. It holds no privileged
channel, no private RPC, and no internal-only feed. Every dashboard, chart,
event console, audit view, and snapshot dialog in the product is assembled from
the calls documented here. The practical consequence is parity: anything the
operator can see or do through the UI, a script can see or do through the API,
with identical fidelity and identical authorisation.
It composes rather than merely proxies. The controller reports whether VPP is
connected; QuantumTouch reports that together with the reply-path stall
detector, the RADIUS reachability verdict, the BMC sensor state, the uplink
gateway probe, and the pool-pressure signal, reduced to a single verdict a
monitoring system can alarm on. The controller emits an audit line; QuantumTouch
merges it with the systemd journal, its own event log, and the captive-portal
access log into one normalised, source-tagged timeline. This composition is the
value the operational plane adds over the raw plane, and it is deliberately
exposed through the API rather than trapped in the UI.
It retains what the controller does not. The BNG controller is a window onto
the present. QuantumTouch runs a sampler that writes to a local ring buffer and
a Prometheus time-series database, retains an append-only event log with
rotation and archival, keeps a sticky event history that survives condition
recovery, and stores versioned configuration snapshots with content hashes.
History, in this system, lives in the operational plane.
A note on the two planes together. An integration does not have to choose.
QuantumTouch fronts the controller on the same TLS listener, under the same
credential, through an explicit passthrough described in The Controller
Passthrough below. A single API key against a single host and port reaches both
the operational endpoints in this document and every raw telemetry endpoint in
the companion document. That is the intended integration posture and it is the
shortest path from a bare box to a populated NMS.
Architecture and the Origins of the Data
Understanding where each value comes from tells an integrator what it can and
cannot mean, how fresh it is, and what happens to it when a dependency fails.