Skip to content

Add APIs

This page explains how to define and add a new KX Sensors API function.

An API is an interface point to a KX Sensors service implemented in kdb+. The interface may be public (accessible from external client programs written in, for example, C, C#, C++, or Java) or private (accessible only to KX Sensors processes). kxs.getAccounts, kxs.getUsers, kxs.getChannels, kxs.addDerivedChannel, kxs.updateLocation, kxs.deleteReadings, etc. are just some of the many core APIs bundled with KX Sensors.

Public APIs are available to any KX client, while private APIs can only be developed and maintained by KX.

Use case 1: Add an API function

There are up to three files involved in creating a new API function:

File Description Required?
An API YAML file (api/newFunc.yaml) Contains the API function metadata, including required parameters, and defines the target process(es). Yes
A q code file (for example, src/newFunc.q) An existing or new file containing the function executed by the API function. Yes
The process config (config/process.yaml) Defines properties for each service class, including which q code files should be loaded. An overlay is required if the target service class must load a new code file containing the function.
  • Create an API YAML, api/getMembers.yaml, and define your API function. The YAML meta is kxs-core/meta/api.yaml.

  • Write the q code for your API, placing it in the appropriate file(s) according to the organization of your code. Only two arguments are required in your API q code: hdr and args. The following example shows the resulting getMembers API:

    .kxs.getMembers:{[hdr;args]
       .sapi.ok .sapi.mdqQuery[`Members;args]
       }

    If your API contains an internal KX function, this is the end of the process.

  • This step is only required if your API q code resides in files not already loaded by the target process. Add the file(s) that you created in the previous step to the libraries definition of the target process in process.yaml. For example, if the hdb was the target and your code was placed in some custom package under src/api/getMembers.q, the hdb section of process.yaml would look as follows:

    - svcClass: hdb
  libraries: [ src/config/systemParams.q, ..., src/api/getMembers.q ]

Note

This path should always be added to the last overlay in KXS_LOAD_DIRS, as that is the value that's realized in memory if the overlay rule is set to fill. If your overlay is a new one, the realized values should be copied from the closest overlay to ensure that everything that is required to load is loaded.

Next steps