APIs

This page describes how KXS APIs are stored as YAML files and structured using the api.yaml metadata template.

APIs are stored as YAML text files in the api directory. All KXS APIs are based on the same meta object: api.yaml in the meta directory. api.yaml is a metadata object or template — a collection of API properties such as parent API, overlay rule (union, first, discard, etc.), service class, aggregation function, feeds, etc. — that describes the nature of the API but is not the API itself.

api.yaml

If this metadata object is defined in a KX package such as KXS Core, it is maintained by KX and should never be modified by KX customers.

api:
  description:
    m-type: string
    m-description: API description
    m-overlay: discard

  parent:
    m-type: symbol
    m-description: Name of "parent" API (unspecified fields in configuration are inherited from parent API)
    m-overlay: first

  isEnabled:
    m-type: boolean
    m-description: Indicates if API is enabled
    m-default: true

  svcClasses:
    m-type: symbols
    m-description: Service classes to which the API should be routed for execution (`svcClass` enumeration values)
    m-overlay: fill
    m-required: true
    m-default: UNKNOWN

  feeds:
    m-type: symbols
    m-description: Feeds associated with data upon which the API depends

  tsArgs:
    m-type: symbols
    m-description: Names of optional arguments (single or pair) specifying date range of data involved in request

  resultType:
    m-type: symbol
    m-description: Data type of result (used to generate null value for failed calls)

  rootFn:
    m-type: symbol
    m-description: Name of the root API function to invoke
    m-required: true

  isPublic:
    m-type: boolean
    m-description: Indicates if API is public (vs. internal use only)
    m-required: true
    m-default: false
. . .

The following table describes each column available in api.yaml:

Column	Definition	Example
api	The name of the API.	<default>
parent	Name of parent API from which the API inherits unspecified configuration fields.
isEnabled	Whether or not the API is enabled.
svcClasses	Service classes to which the API should be routed for execution (svcClass enumeration values).	UNKNOWN
feeds	IDs of feeds associated with data upon which the API depends.
tsArgs	The list of arguments to the API that specify the time range used. It can either be one element (e.g. ts) or a pair (e.g. startTS, endTS). These arguments are then looked at by GW to determine the "range" of the request, which it uses to make the appropriate routing decisions to the RDB, IDB, or HDB. If you do not specify a time range, your query is routed to all databases even though the data that you are looking for might only be in RDB and IDB (for example, very recent data). As a result, your query could be slower and consume more resources than necessary.
resultType	Data type of result (used to generate null value for failed calls).
rootFn	Name of the root API function to invoke.
isPublic	Indicates if API is public (vs. internal use only).
classFns	Classification function used to add routing preference fields to incoming API header.	.sapi.classStatic
preExecFns	Optional pre-execute functions that may alter input, terminate the API, or have side effects prior to API execution.
postExecFns	Optional post-execute functions that may alter the response or have side effects after API execution.
preAggFns	Optional pre-aggregation functions that may alter input, terminate the API, or have side effects before API aggregation.
aggFn	SAPI aggregation function used to combine or further process results from execution targets.	.sapi.aggNoop
postAggFns	Optional post-aggregation functions that may alter the response or have side effects after API aggregation.
reqUniform	Indicates that results from execution targets must be uniform with respect to database vintage at time of execution.	false
isMutating	Indicates whether or not the API creates or mutates data within KX Sensors.	false
isSolo	Indicates if dispatch (including GW) must be to a single node.	false
duration	Categorization of expected API duration (sapiDur enumeration value).	MED
priority	API priority, which may influence execution sequence of queued requests (sapiPriority enumeration value).	NORMAL
timeout	Operation timeout in seconds. If not specified, the timeout associated with configured duration is used.
reqLogFn	Request parameter logging function.	.sapi.fmtReq
iresLogFn	Intermediate logging function used on individual execution results prior to aggregation.	.sapi.fmtRes
aggLogFn	Intermediate logging function used on collected execution results prior to aggregation.	.sapi.fmtReq
resLogFn	Final response payload logging function.	.sapi.fmtRes
isLog	Indicates if framework-level request/response logging is performed during API processing.	true
isTrace	Indicates if full trace-level logging is performed during API processing (all facilities).	false
minVersion	If you specify a minimum version for an API and the current version of the API on a given node is less than the minimum, that node is not considered by GW to service a request.
version	The current version of an API.

Set up API overrides

The overlay rules for APIs are identical to the overlay rules for configuration objects. See Overlay rules for configuration objects.

API overrides are subsets of the default metadata object defined in api.yaml, and need only contain the columns that differ from the default. Any empty columns inherit either populated columns from a lower-level override or, failing that, the default values in kxs-core. The following example shows an api.yaml override:

api:
  minVersion: 1.03
  version: 1.21

Your API override must be placed in the appropriate api/ and src/ directories of your overlay directory list.

Next steps

• Add APIs
• Call APIs over REST