Skip to content

API registration

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.

Note that when making API calls via 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 .sapi.meta objects (see Meta Builders).
    • Empty list to not include any metadata for the function.

Metadata builders

For convenience, we have a set of meta building APIs for defining metadata. A description of each API is given below, and examples are given in (Examples).

The meta-building APIs create entries to populate the metadata fields of APIs and aggregation functions. They live in the "Service API" (sapi) repo/namespace (this is a repo that was created for code shared between DA and SG).

  • .sapi.metaDescription - Creates a description entry for an API/aggregation function's metadata. Parameters:
    • descr - string - Description.
  • .sapi.metaParam - Creates a param entry for an API/aggregation function's metadata. Parameters:
    • param -dictionary - Dictionary containing 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.
  • .sapi.metaReturn - Creates a return entry for an API/aggregation function's metadata. Parameters:
    • return - dictionary - Dictionary containing any subset of the following keys:
      • type - short|short[] - Possible type(s) for the return.
      • description - string - Plain text description of the return value.
  • .sapi.metaMisc - Creates a miscellaneous metadata entry. Parameters:
    • misc - dictionary - Dictionary containing any subset of the supported misc fields:
      • safe - boolean - True if API can be retried safely in the event of a failure, false otherwise.

Examples

//--------------------------------------------------------------------------------
// Metadata using JSON.
//--------------------------------------------------------------------------------

// API.
apiMetaData:()!()
apiMetaData[`description]:"Simple 'select ... from ... where ...' API."
apiMetaData[`param]:flip
    (`name      ,`type  ,`required  ,`default   ,`descr)!flip(
    (`table     ;98h    ;1b         ;()         ;"Table to query");
    (`filter    ;0 10h  ;0b         ;()         ;"Filter (in functional or string form).");
    (`col       ;11 -11h;0b         ;`sym`time  ;"Column(s) to select.")
    )
apiMetaData[`return]:`type`description!(98;"Result of the select.")

.da.registerAPI[`myAPI;apiMetaData] // Or, equivalently ...
.da.registerAPI[`myAPI;.j.j apiDescr] // Stringed

// Agg function.
aggMetaData:()!()
aggMetaData[`description]:"Takes the sum."
aggMetaData[`param]:`name`type`descr!(`x;2 4 5 6 7 8 9h;"Some list of summable vectors.")

.sgagg.registerAggFn[`myAggFn;aggDescr;()] // Or equivalently ...
.sgagg.registerAggFn[`myAggFn;.j.j aggDescr;()] // Stringed

//--------------------------------------------------------------------------------
// Description using just a plain string. This populates just the `description`
// field. This offers a quick way to minimally describe how an API/agg function
// should be used.
// These calls would be equivalent to just using the `description` key in the
// examples above.
//--------------------------------------------------------------------------------

.da.registerAPI[`myAPI;"Simple 'select ... from ... where ...' API."]

.sgagg.registerAggFn[`myAggFn;"Takes the sum.";()]

//--------------------------------------------------------------------------------
// Metadata using a default dictionary. This only populates the `params` field.
// Also note that it marks all parameters optional.
//--------------------------------------------------------------------------------

.da.registerAPI[`myAPI;`table`filter`col!(`trade;();`sym`time)]

//--------------------------------------------------------------------------------
// Metadata using the meta-building APIs.
//--------------------------------------------------------------------------------

.da.registerAPI[`myAPI;
    .sapi.metaDescription["Simple 'select ... from ... where ...' API."],
    .sapi.metaParam[`name`type`isReq`description!(`table;-11h;1b;"Table to query")],
    .sapi.metaParam[`name`type`isReq`default`description!(`filter;0 10h;0b;();"Filter (in functional or string form).")],
    .sapi.metaParam[`name`type`isReq`default`description!(`col;11 -11h;0b;`sym`time;"Column(s) to select.")],
    .sapi.metaReturn[`type`description!(98h;"Result of the select.")],
    .sapi.metaMisc[enlist[`safe]!enlist 1b]
    ]

// Note: Can only have 1 parameter for an agg function.
.sgagg.registerAggFn[`myAggFn;
    .sapi.metaDescription["Takes the sum."],
    .sapi.metaParam[`type`description!(2 4 5 6 7 8 9h;"Some list of summable vectors.")],
    .sapi.metaReturn[`type`description!(6 7 8 9h;"The sum of the lists.")];
    ()
    ]

//--------------------------------------------------------------------------------
// No description at all.
//--------------------------------------------------------------------------------

.da.registerAPI[`myAPI;()]

.sgagg.registerAggFn[`myAggFn;();()]