Skip to content

REST-server library API reference

.com_kx_rest Initialization init Initialize the namespace

Registration register Register an endpoint reg.data Define a data item: input parameter or object member reg.header Define a HTTP-header based input parameter reg.body Define the expected POST body in the request reg.output Define the output of the endpoint reg.object Define an object for use as data element, body, or output reg.default Get object populated with default values

Utilities util.throw Throw an error util.response Construct response util.httpResponse Construct HTTP response

Request processing process Process an incoming HTTP request

.com_kx_rest.init

Initialize the library namespace

.com_kx_rest.init[]

Initializes the library namespace.

Invoke before other framework functions

.com_kx_rest.process

Process an incoming HTTP request

.com_kx_rest.process[op;x]

Where

  • op (symbol) is the default REST operation, used if http-method header is not present
  • x (list) is the incoming request: the argument to .z.ph and .z.pp.

the operation is determined from http-methodcustom header if present, otherwise value of the op argument is used.

Example:

This example hooks .com_kx_rest.process functions to be the handler for both of .z.ph and .z.pp functions.

.z.ph:.com_kx_rest.process `GET
.z.pp:.com_kx_rest.process `POST

.com_kx_rest.reg.body

Define the expected POST body in the request

.com_kx_rest.reg.body[nm;typ;isReq;dfv;dscr]

Where

nm     symbol   name of parameter/item
typ    symbol   name of object (defined with reg.object)
isReq  bool     whether the body is required
dfv    any      default value, which must be of a type 
                compatible with the object
dscr   string   human readable description

defines the input request body expected by the post-based endpoint.

Create a new customer object:

.com_kx_rest.reg.object[`customerObj;
  .com_kx_rest.reg.data[`id;-6h;1b;0N;"Customer ID"],
  .com_kx_rest.reg.data[`name;10h;1b;"";"Customer name"] ]

.com_kx_rest.register[`post;"/customers";
  "Creates one or more customers";
  {`customers upsert cols[customers]#x`data;count customers};
  .com_kx_rest.reg.body[`customerObj;1b;::;"One or more customer object"] ]

.com_kx_rest.reg.data

Define a data item

.com_kx_rest.reg.data[nm;typ;isReq;dfv;dscr]

Where

nm      symbol         name of parameter/item
typ     short/symbol   q datatype, or object name (defined with reg.object)
isReq   bool           whether parameter is required
dfv     any            default value; must be of a type compatible with typ
dscr    string         human-readable description

defines a data item that can be used as:

  • path-parameter or query-string based input parameter (when invoked in the context of specifying the params argument of the .com_kx_rest.register function)
  • an element of an object (when invoked in the context of specifying the items argument of the .com_kx_rest.reg.object function).

.com_kx_rest.reg.default

Default value of an object

.com_kx_rest.reg.default[nm]

Where nm (symbol) is the name of an object, returns its default value.

See reg.object for an example.

.com_kx_rest.reg.header

Define a HTTP-header based input parameter

.com_kx_rest.reg.header[nm;typ;isReq;dfv;dscr]

Where

nm     symbol        name of parameter/item
typ    short|symbol  q datatype, or object name (defined using `reg.object`)
isReq  bool          whether parameter is required
dfv    any           default value, which must be of a type that is
                     compatible with `typ`
dscr   string        human readable description

defines a HTTP header-based input parameter.

.com_kx_rest.reg.object

Register an object

.com_kx_rest.reg.object[nm;items;dscr]

Where

nm      symbol   name of object: must be globally unique
items   tbl      one or more data elements, defined with .com_kx_rest.data
dscr    string   human-readable description

registers the object, which can then be a used as the datatype of an input parameter, request body, or output.

The example defines an object that contains another object, and an endpoint that takes the containing object as input, and returns the nested one.

.com_kx_rest.reg.object[`nestedObj;
  .com_kx_rest.reg.data[`prop1;6h;1b;0#0Ni;"property 1"],
  .com_kx_rest.reg.data[`prop2;11h;1b;0#`;""],
  .com_kx_rest.reg.data[`prop3;0h;0b;("v1";"v2");""],
  .com_kx_rest.reg.data[`prop4;11h;0b;1#`a_value;""] ]

.com_kx_rest.reg.object[`containerObj;
  .com_kx_rest.reg.data[`id;-6h;0b;100;"id"],
  .com_kx_rest.reg.data[`name;10h;0b;"xyz";"a name"],
  .com_kx_rest.reg.data[`properties;`nestedObj;0b;
    .com_kx_rest.reg.default`nestedObj;"A nested object"] ]

.com_kx_rest.register[`post;"/nested";
  "demonstrates nested object";
  {x[`data]`properties}; // Returns nested object
  .com_kx_rest.reg.body[`containerObj;0b;
    .com_kx_rest.reg.default`containerObj;
    "One or more container objects"],
  .com_kx_rest.reg.output[`nestedObj;1b;"Resulting object"] ]

.com_kx_rest.reg.output

Define the output of the endpoint

.com_kx_rest.reg.output[typ;isReq;dscr]

Where

typ     symbol   name of object, defined with reg.object
isReq   bool     whether parameter is required
dscr    string   human-readable description

defines the output of the endpoint.

.com_kx_rest.util.httpResponse

HTTP response from status code, headers, and body

.com_kx_rest.util.httpResponse[]

where

code      string   HTTP status code
headers   dict     headers: keys and values must be strings
cbt       string   content body, 
                   encoded according to Content-Type set in headers

returns endpoint’s HTTP response

allowing control over the HTTP headers.

.com_kx_rest.util.response

HTTP response from status code, content type, and content

.com_kx_rest.util.response[code;cnttype;cnt]

where

code      string   HTTP status code, e.g. "201"
cnttype   symbol   Content type: one of the keys of .h.ty
cnt       string   Content body, encoded according to cnttype

returns HTTP response

.com_kx_rest.util.throw

Signal an error

.com_kx_rest.util.throw[x;y]

where

x               string   error message
y               string   error information, e.g. input parameters

signals an error.