Skip to content

Client interfaces

This page lists the interfaces an external application can use to connect to KX Sensors, and explains what each one requires on the server.

An external application connects to KX Sensors to do one of two things: publish sensor readings into the system, or call APIs to query and mutate data. KX Sensors provides several interfaces for this, with different language support, delivery guarantees, and setup requirements.

Available interfaces

Interface Languages Use it to
SAPI C, C#, Java, Python Publish readings, call APIs, and receive message queue deliveries over the native qIPC protocol. This is the full-featured interface.
REST Any HTTP client Call public APIs over HTTP/JSON. No KX libraries required on the client.
Message queues C, C#, Java, Python (through SAPI) Receive notifications and acknowledgements from KX Sensors with at-least-once delivery.

SAPI is the Sensor Application Programming Interface: a set of client libraries that handle process discovery, connection management, request routing, and publishing. From v3, SAPI is implemented in C, and the C#, Java, and Python libraries are thin layers over that C core. For the differences from the v2 interface, see What's new.

Choosing between SAPI and REST

Use SAPI when you need to:

  • Publish sensor data. REST has no publishing path.
  • Receive message queue deliveries.
  • Control query routing through SAPI request header properties such as routePrefs, dur, and priority.
  • Avoid the HTTP and JSON serialization overhead on high request rates.

Use REST when you need to:

  • Call APIs from a language SAPI doesn't support, or from a browser or integration platform.
  • Avoid deploying and linking KX client libraries.
  • Work against a generated OpenAPI specification. See Discover available endpoints.

Both interfaces call the same public APIs and both go through the Gateway.

What is not supported

  • Subscribing to a stream from a client. SAPI has no subscribe method in v3. Message queue listeners provide at-least-once delivery of notifications, but there is no client-side subscription to an EMS stream.

Server-side prerequisites

Before a client can connect, the following must be true of the KX Sensors deployment.

For SAPI clients

Requirement Where you configure it
A reachable qetcd process on at least one node, for Discovery. qetcd runs on every node. See Key processes.
At least one GW (Gateway) instance, to accept API requests. manifest.yaml
At least one RP (Response Process) instance, to return API results. manifest.yaml
For publishing: an external EMS stream, and a feed mapped to it. ems.yaml and feed.yaml
For message queue listeners: an MQ instance. manifest.yaml

For REST clients

An SGW (Synchronous Gateway) instance with isREST: true set in systemParams.yaml. See Call APIs over REST.

Ports and connection direction

Client connections use the node's base port, set by KXS_BASE_PORT in kxsenv and 20000 by default. The offsets relevant to clients are:

Offset Port
+3 qetcd external client port, used by SAPI clients for Discovery
+4 qetcd external client port for TLS, used by SAPI clients when TLS is enabled
+6 REST bridge port. Override it with KXS_REST_PORT.
+11 Dashboard port

Most connections run from the client to the server, but not all. Response Processes open connections to SAPI clients to return API results, so your firewall rules must allow inbound connections to the client host on the port range the client listens on. For the full port list and firewall guidance, see Network requirements.

Authentication

KX Sensors authenticates clients with a username and password held in an encrypted credentials database in etcd. Authentication is enabled per service class in manifest.yaml, so a deployment can require credentials on some entry points and not others.

  • SAPI sends the username and password as part of the qIPC handshake. Set them in the SAPI configuration object — see Connect with SAPI.
  • REST uses HTTP basic authentication: Authorization: Basic <base64 of username:password>. See Authentication.

Credentials are sent in plain text unless you enable TLS. For the full authentication model, including roles and how to add users, see User authentication.

Encryption

Client connections support TLS. On the server, you set a TLS mode per service class in manifest.yaml, and for external publishing you set the tls mode on the EMS stream in ems.yaml. On the client, you enable TLS in the SAPI configuration object and supply a CA certificate, a client certificate, and a key.

Next steps