API layers and calling boundaries

Choose APIs by caller responsibility, not by backend implementation. The contract has five practical layers.

flowchart LR
    A[Public: health and sign-in] --> B[Business: devices, video, recording, RTC]
    B --> C[Admin: config, users, nodes]
    C --> D[Node operations: controlled Agent]
    D --> E[Internal callbacks: product components only]

Public connection entries

Health, sign-in, captcha, refresh, and first-time bootstrap are the few calls available without a Bearer token. Rate limits and login defense still apply.

Third-party business APIs

Devices, channels, streams, recordings, unified protocol views, and RTC are the normal integration surface. Call them from your backend with a dedicated least-privilege token.

Prefer unified resources and channel APIs. Use GB28181 or ONVIF-specific routes only for protocol-specific behavior.

Administrator APIs

Users, roles, tokens, raw configuration, server file browsing, host tuning, and node lifecycle operations change platform security or runtime behavior. Some require an interactive administrator session in addition to permissions.

Real-time and streaming APIs

WebSocket, NDJSON, WHIP/WHEP, file streams, and Range downloads need protocol-specific handling for reconnects, sequence replay, SDP, session release, streaming, and cancellation.

Internal service APIs

Node heartbeats, command result callbacks, agent-local APIs, media callbacks, and protocol result callbacks belong to trusted product components. They are documented for contract auditing, not as third-party extension points.

The correct completion loop

A complete workflow is: request, authorization, command or resource creation, asynchronous execution, state/event callback, then final-state verification. Keep resource, command, task, session, and Trace IDs; after a timeout, read current state before retrying a write.