Edge REST API

Use REST where request-response is the right contract

REST over HTTP is a useful boundary for configuration, lookup, bounded command requests, reports, and integrations with business applications. Its strengths are familiar tooling, explicit resources, widely supported security mechanisms, and a request-response mental model. It is not automatically the best transport for high-rate telemetry, real-time media, continuous device state, or a local safety path.

At the edge, REST should be assigned a clear role. An API may sit on an industrial PC beside equipment, inside a gateway, in a local model sidecar, or in an enterprise service. Each location changes latency, reachability, data ownership, and incident response. The central question is not "does this system have an API?" but "which responsibility may depend on that API being available?"

Banalytics is the local orchestration and monitoring layer around such interfaces. It can connect physical sources, run local tasks, retain configured data, create events and actions, monitor the node, and supervise approved helper services. It should not be described as a general-purpose REST API gateway or native OPC UA/REST integration where a specific connector has not been implemented.

Place Banalytics at the physical and operational boundary

This model preserves local autonomy. If an upstream REST service is slow or unavailable, the edge node can continue acquisition, local processing, and the defined event workflow. The remote service receives a delayed, retried, or reconciled outcome according to an explicit contract; it does not become a hidden dependency for every local signal.

Choose a pattern that matches the workload

The Process component is a useful operating boundary for a local API sidecar, bridge, data collector, or AI service. It can start and stop the process tree, capture output or redirect it to files, and run the helper under a named lifecycle. The helper remains its own implementation with its own API contract.

Specify failure behaviour as carefully as the endpoint

A production edge API contract needs more than a path and a JSON example. It should define asset identity, source time, units, schema version, allowed request rate, response semantics, error classes, authentication, authorisation, idempotency, retention, audit requirements, and what happens when either side restarts.

• Use resource identity that survives replacement. Avoid relying only on a transient host address or UI label.
• Separate command request from completion. A 202 Accepted or TCP response is not proof of a physical outcome; define status and acknowledgement resources.
• Carry source time and quality. Arrival time alone cannot distinguish live data, a buffered replay, and a stale measurement.
• Make retries safe. Use idempotency keys or correlation IDs for event-driven delivery and commands.
• Bound resources. Set connection, request, and response-size limits, then expose timeout and backlog conditions as operational signals.
• Version deliberately. Add fields compatibly, publish schema changes, and retain a rollback plan for both client and service.

Keep custom HTTP work explicit and reviewable

Banalytics provides general extension points rather than a claim of a universal built-in REST connector. A small, trusted integration can use Java Action for controlled in-process logic; its documented default imports include common networking APIs. A command-line wrapper can use Command Line Action for a short, bounded call. A larger, long-running or dependency-heavy integration belongs in a separately supervised Process or a purpose-built module.

For local service-to-service data exchange, ZeroMQ Socket or MQTT may be a better fit than HTTP when the workflow is event-driven or throughput-sensitive. The local Banalytics layer can then convert selected service output into events, dashboards, retained records, and approved external delivery through Event Manager. Keep the specialist HTTP service independent from the physical operating workflow wherever possible.

The WebRTC HTTP Proxy has a different role: it opens an agent-reachable trusted HTTP or HTTPS application inside the portal through an authenticated WebRTC connection. It uses allow-lists, limits, and a sandboxed rendering model. It is intended for tested internal administration pages and embedded-device interfaces, not as a transparent REST proxy or general Internet browser.

Do not turn convenience APIs into an uncontrolled control plane

Edge interfaces often sit close to cameras, machinery, buildings, and sensitive local networks. Apply least privilege at each boundary: separate service identities, restrict host reachability, use TLS where the route requires it, store secrets outside source code, log privileged requests, and give read-only integrations no command permission.

A REST request that can affect equipment must be treated as a supervised command workflow. The local control system validates interlocks and current state; Banalytics may coordinate the authorised workflow and expose its result, but it does not replace PLC, DCS, SIS, or other safety authority. For day-to-day operation, observe the node itself through System Monitor so host pressure, storage exhaustion, and runtime faults are visible beside interface errors.

Use a REST boundary when it improves ownership and operability

1. Place Banalytics where the physical sources, local tasks, and immediate response need to survive independently.
2. Put REST at a bounded service or enterprise boundary, with documented resources and owners.
3. Use a local sidecar or gateway for custom REST needs rather than implying unsupported native connectivity.
4. Export the smallest useful, contextualised outcome instead of every raw input.
5. Exercise disconnection, timeout, restart, duplicate request, and unauthorised-request scenarios before production rollout.

A good edge REST architecture makes each interface replaceable and each failure diagnosable. Banalytics contributes the local operating shell: it keeps the system close to equipment, observable by operators, and independent of the availability of a single remote API.