Skip to content

API registration

This page describes how to register APIs, aggregation functions, and UDAs with metadata so that their signatures and behavior are discoverable through the .kxi.getMeta API.

API and aggregation functions can be registered with metadata about the function that is subsequently surfaced by the .kxi.getMeta API (see "SG - API"). The metadata is a dictionary containing the following keys:

  • description - string - Plain text description of the function.
  • params - dictionary[] - List of parameters to the function, each of which consists of any subset of the following keys:
    • name - symbol - Name of the parameter.
    • type - short|short[] - Possible type(s) for the parameter.
    • isReq - boolean - Whether the parameter is required (this is only meaningful for APIs).
    • default - any - Default value of the parameter if it is not required (this is only meaningful for APIs).
    • description - string - Plain text description of the parameter.
  • return - dictionary - Return value of the function, which consists of any subset of the following keys:
    • type - short|short[] - Possible type(s) for the return.
    • description - string - Plain text description of the return value.
  • misc - dictionary - Miscellaneous metadata values. Currently only supports one value:
    • safe - boolean - Only applicable to APIs. True if the API can be retried safely in the event of a failure, false otherwise.

When making API calls through HTTP, parameters are cast to the first type, if it is defined. If no type is defined, the parameter is not cast

The metadata of an API/aggregation function is a parameter in the registration function (.da.registerAPI for API functions, and .sgagg.registerAggFn for aggregation functions, see "DA" and "SG" configuration pages).

In either case, the metadata can be passed to the appropriate registration function in any of the following formats:

  • string - A string which may be:
    • Serialized JSON of the format described above, which would allow function metadata to be stored as JSON files to be read into the q code. Note that default values for params in this case are cast to the first type, if it is defined. If no type is defined, the default value is not cast.
    • Non-serialized JSON string. In this case, the string is used as the function description, and the params, return, and misc keys are left empty.
  • dictionary - A dictionary, which may be:
    • A dictionary of the format above.
    • A dictionary of default values (only applicable to APIs). In this case, we populate the params value of the metadata with the default values given, and the description, return, and misc keys are left empty. Note also that this marks all parameters as optional.
  • list - A list which may be:
    • List of .kxi.meta objects (see Meta Builders).
    • Empty list to not include any metadata for the function.

UDA Registration

.kxi.registerUDA registers a UDA to ensure that is it surfaced by the .kxi.getMeta API and available for querying.

The .kxi.registerUDA function accepts a dictionary with the following keys:

Key Name Required Type Description
name Yes Symbol The name of the UDA when called using the Service Gateway. *
query Yes Symbol The name of the function that runs on the DAPs and retrieves the partials for aggregation.
aggregation No Symbol The name of the function that runs on the aggregator and combines the partial results from the DAPs.
metadata No List Metadata about the properties of the UDA. It's recommended to use the metadata builders described in the Meta-building APIs section.

The following example registers a UDA called .exampleuda.countBy that includes a query function named .exampleuda.countByQuery, an aggregation function .exampleuda.countByAgg; and a metadata variable created using .kxi.metaDescription.

.kxi.registerUDA `name`query`aggregation`metadata!(`.exampleuda.countBy;`.exampleuda.countByQuery;`.exampleuda.countByAgg;metadata);