Skip to content

Call APIs over REST

This page explains how to enable REST support and call your KX Sensors APIs over HTTP/JSON instead of native kdb+ IPC.

REST support exposes your public APIs (isPublic: true in api.yaml) as JSON-over-HTTP endpoints, without requiring changes to the APIs themselves. Endpoints are generated automatically from the SAPI registry, so any public API you add is reflected in the available REST endpoints.

How it works

Two components provide REST access:

  • SGW (Synchronous Gateway) hosts the REST framework and registers one or more HTTP endpoints for each public API in the SAPI registry. It forwards incoming requests to GW asynchronously and holds each connection open until GW responds.
  • http2ipc is a lightweight bridge process that terminates HTTP/JSON connections from clients and forwards them to SGW over qIPC. It uses a pool of connections to handle concurrent REST requests.
flowchart LR
    Client -- JSON/HTTP --> Bridge[http2ipc bridge]
    Bridge -- qIPC --> SGW
    SGW -- async, deferred response --> GW
    GW --> SGW --> Bridge --> Client

SGW manages the entire lifecycle of the http2ipc bridge, so you don't need to configure or run the bridge separately. SGW also re-registers endpoints when a dynamic upgrade changes the API set.

Enable REST support

  1. Include the SGW service class in manifest.yaml for the nodes that should serve REST. Like GW, SGW is single-instance.
  2. Set isREST: true in systemParams.yaml and restart SGW.

The following related parameters are optional and use their default values if you don't specify them:

Parameter Definition Default
isREST Master switch that enables REST support on SGW. false
restMode* Specifies the endpoint-mapping mode: restful, faithful, or unset for both. See Endpoint mapping below. (unset)
restPoolSize* Maximum number of simultaneous REST requests the http2ipc bridge accepts. 255
restBridgeStartInterval Specifies how long, in milliseconds, SGW waits for the bridge to connect after starting it. If the bridge doesn't connect within this interval, SGW logs a fatal error and exits. 2500
restBridgeRestartInterval Indicates how long SGW waits after the bridge connection drops before restarting it. 250
restBridgeLog* Whether the bridge writes its own log file. Enable this parameter for debugging only. false
* Static parameter. Changes require a process restart. See System parameters systemParams.yaml.

By default, the bridge listens on the port specified by KXS_BASE_PORT (environment variable) + 6. To override this, set KXS_REST_PORT as an environment variable (for example in kxsenv).

Authentication

REST doesn't have separate authentication settings; it reuses what is configured for SGW. If the SGW entry in manifest.yaml has auth: true, REST clients must provide valid KX Sensors credentials in the following header: Authorization: Basic <base64 of username:password>

For more information, see User authentication.

If credentials are missing or invalid, the server returns an HTTP 401 response with a WWW-Authenticate header. If authentication isn't enabled for SGW, the server ignores the Authorization header.

TLS

To enable HTTPS for REST clients, set tls: <mode> on the SGW entry in manifest.yaml. For more information, see In-transit TLS encryption.

TLS applies only to the client-facing HTTP connection. The bridge connection to SGW is always local and uses unencrypted qIPC.

Endpoint mapping

Each public API gets one or more endpoints, depending on its name prefix and the restMode system parameter.

Official endpoint

Every public API has an endpoint with the same name. The endpoint is always called with POST, regardless of the API operation, to support complex parameter types consistently across all APIs:

API Endpoint
.kxs.getUsers POST /kxs/getUsers
.kxs.addUser POST /kxs/addUser
.kxs.updateUser POST /kxs/updateUser
.kxs.deleteUsers POST /kxs/deleteUsers

RESTful-style endpoints

APIs with names that start with get, add, update, or delete also have one or more RESTful alternative endpoints. These endpoints omit the prefix from the path.

get.

For example, .kxs.getUsers supports endpoints where all parameters are provided in the query string:

GET /kxs/Users
GET /kxs/Users?userIDs=1

If the API takes no parameters, or its first parameter is an int, long, symbol, or a list of one of these types, it also has an endpoint that includes the first parameter in the path. Any remaining parameters are provided in the query string. Specify list parameters as a comma-separated list:

GET /kxs/Users/{userIDs}
GET /kxs/Users/1002,1003

add.

For example, for .kxs.addUser provide all parameters in the JSON request body:

POST /kxs/User

curl -sX POST http://localhost:8080/kxs/User \
  -H 'Content-Type: application/json' \
  -d '{"orgID":1,"name":"user123","extUserID":"u123"}'

update/delete.

If the first parameter is a supported type (as described for get above), it goes in the path, The rest go in the JSON body (update) or query string (delete). Otherwise, there's no ID segment and all parameters go in the body/query string as usual.

For example, .kxs.updateUser and .kxs.deleteUsers provide the following endpoints:

PUT /kxs/User/{userID}
DELETE /kxs/Users/{userID}

curl -sX PUT http://localhost:8080/kxs/User/1 \
  -H 'Content-Type: application/json' -d '{"name":"SYSTEM"}'

curl -sX DELETE http://localhost:8080/kxs/Users/1

Override endpoint mapping with restMode

restMode Behavior
(unset — default) Generates both the official endpoint and any RESTful alternative endpoints for each API.
restful Generates only RESTful alternative endpoints. APIs without a supported prefix (get, add, update, or delete) still get the official endpoint.
faithful Generates only official (non-RESTful) endpoints.

Request and response format

For official endpoints and RESTful POST and PUT endpoints, specify parameters in a JSON request body with Content-Type: application/json. You can omit the request body if the API has no required arguments.

Pass SAPI headers as custom HTTP headers:

Header Maps to Type Default
Sapi-User-Id userID int 1
Sapi-Org-Id orgID int 1
Sapi-Log-Corr logCorr string generated (rest_<n>) if omitted
Sapi-Timeout timeout, in seconds int 0 (no timeout)

Every response has the same structure, whatever the endpoint:

{
  "sapi": {...},
  "data": []
}
  • sapi — the SAPI response header dictionary (rc, ac, ai, reqCorr, svcTm).
  • data — the API's result.

For example, GET /kxs/Users?userIDs=1 returns:

{
  "sapi": {
    "rc": "OK",
    "ac": "OK",
    "ai": [],
    "reqCorr": 5,
    "svcTm": 3
  },
  "data": [
    {
      "userID": 1,
      "orgID": 1,
      "extUserID": "SYSTEM",
      "name": "SYSTEM",
      "tzID": 1
    }
  ]
}

The HTTP status reflects the SAPI result code (sapi.rc):

HTTP status SAPI result code (rc) Meaning
200 OK Success.
400 APP_DB Validation error — missing/invalid argument, wrong type, or malformed JSON body.
404 NOT_SUPPORTED No such endpoint.
500 ERR The API itself signaled an error.
504 TIMEOUT The request exceeded its Sapi-Timeout.

Discover available endpoints

SGW exposes two built-in endpoints for inspecting the current endpoint set:

Endpoint Description
GET /rest/openapi.json Returns the OpenAPI (3.0) specification for the currently configured endpoints, generated live from the SAPI registry.
GET /rest/ls Returns the HTTP method and path for each currently configured endpoint.

The OpenAPI specification reflects the public APIs available in your deployment. Use /rest/openapi.json as the source of truth for your environment. You can retrieve the specification directly for use with Swagger or other OpenAPI tools.

Limitations

REST support has the following limitations:

  • Response caching is a client-side concern — REST support doesn't cache responses on the server.
  • Paging is not supported.
  • setMD and batchMD aren't supported because nested parameter types for MDL entities aren't yet defined in SAPI.
  • API versioning for REST endpoints is not supported.

Next steps