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 forparams
in this case are cast to the firsttype
, if it is defined. If notype
is defined, thedefault
value is not cast. - Non-serialized JSON string. In this case, the string is used as the function
description
, and theparams
,return
, andmisc
keys are left empty.
- 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
- 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 thedescription
,return
, andmisc
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.
- List of
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;();()]