API Proxy
The SBN Media API Proxy - the web entry point that SBN Anywhere and SBN Video clients and the dashboard connect through.
API Proxy
The API Proxy is the single web entry point into SBN Media. SBN Anywhere and SBN Video clients, the SBN Media dashboard, and other applications all connect through it. It receives web requests, forwards them to the right service, and returns the response.
Overview
The API Proxy turns incoming web requests into messages for the services that do the work, then relays the result back. It is the only SBN Media service that normally needs to be reachable from outside the host - everything else sits behind it.
It also serves the SBN Media dashboard and the API documentation, and it is the connection point a browser uses to start a live video session.
- Runs: When configured; at most one per host. A host that serves video or web clients needs one.
- Required: Yes, for any host that serves clients. Without it, SBN Anywhere and SBN Video clients cannot reach SBN Media.
- Depends on: NATS, which it uses to reach the other services.
Configuration
The API Proxy is configured under the apiproxy namespace. View the defaults with ./sbn-media config eject and set host-specific overrides in sbn-media.local.yaml.
Setting | Default | Description |
|---|---|---|
| 8081 | The port the API Proxy listens on. |
| empty | The address to bind to. Empty listens on all addresses. |
| http |
|
| empty | The URL clients use to reach the API Proxy. Defaults to |
|
| Which web origins may call the API Proxy. In production, set this to the origins of the applications that use it - for example your SBN Anywhere or SBN Video front end - rather than |
| true | Require a valid token on requests. Tokens are checked against the API Engine. |
| empty | Protects the administrative routes. If it is not set, those routes are unavailable. |
| empty | Token required to read Prometheus metrics. |
| 10485760 | Largest request body accepted, in bytes (10 MB). |
| see below | Turns individual feature routes on or off. |
Routes
Each feature of the API Proxy is a route that can be turned on or off under apiproxy.routes. A route that is off is not available. Routes marked "admin" require apiproxy.adminToken to be set and supplied by the caller.
Route | Default | Enables |
|---|---|---|
| on | The SBN Media dashboard and sample client pages. |
| on | The API documentation at |
| on | Live video connections for SBN Video clients. |
| on | Access to recorded video. |
| on | Object-detection endpoints. |
| on | Scene-change detection endpoints. |
| on | Re-identification queries. |
| on | The device registry. |
| on | Action-plan script endpoints. |
| on | Listing the available text-to-speech voices. |
| on | Foresight invite links. |
| on | Service control - start, stop, restart, health (admin). |
| on | Live and historical logs (admin). |
| off | Performance profiling, for diagnostics (admin). |
| off | Download raw call captures, for diagnostics (admin). |
| off | A local file server, for testing only. |
Example:
After changing these settings in sbn-media.local.yaml, reload the configuration for them to take effect. Changing the listen address or port requires restarting the service.
FAQ
SBN Video clients cannot connect. What should I check?
First confirm the API Proxy is running and reachable - check it in the dashboard, or open its address in a browser. Then confirm the port (8081 by default) is open on the network, and that apiproxy.allowOrigins includes the origin of the client application (for example SBN Anywhere or SBN Video). If the service will not start, run it in the foreground with sbn-media service exec apiproxy -ld to see the startup error.
How do I secure the API Proxy?
Use https for apiproxy.protocol, set apiproxy.allowOrigins to the origins of the applications that use it (such as SBN Anywhere or SBN Video) instead of *, keep apiproxy.requireToken set to true, and set a strong apiproxy.adminToken. Leave the diagnostic routes (pprof, signalTrace, fileserver) off unless you are actively using them.
Why am I getting an unauthorized (401) response?
apiproxy.requireToken is on, so every request must carry a valid token, which the API Proxy checks against the API Engine. The administrative routes (service control, logs, profiling, signal trace) need the admin token as well - confirm apiproxy.adminToken is set and that the caller is supplying it.
Do I need an API Proxy on every host?
You can run at most one per host, and you need at least one that clients can reach. In a multi-host setup it is common for each host to run its own so that a client can connect through any of them. A common production configuration places the API Proxy in a DMZ on several servers that load-balance incoming requests; the requests are then carried out by the other services behind them.
Related pages
- SBN Media Overview (
SBN-Media/overview) - Installing and Configuring SBN Media (
SBN-Media/installation) - Watchdog (
SBN-Media/Platform/watchdog) - Firewall (
SBN-Media/Configuration/firewall)