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.register

This function registers an endpoint

op     {symbol}   The operation (typically one of `get`, `post`, `put` or `delete`).
path   {string}   Path. Supports variables using {var} syntax (e.g. "/users/{id}").
dscr   {string}   Human readable description.
fn     {fn}       Handler function (described below).
params {tbl}      One or more user input definitions, or empty list if no parameters
                  are defined. See .com_kx_rest.data for details.

Example:

.rest.register[`get;"/customers/{id}";
    "Returns one or more customers by their IDs";
    {select from customers where id in x[`arg;`id]};
    .rest.reg.data[`id;6h;1b;0;"One or more customer IDs"]
    ];

The handler function is monadic, and is expected to receive a dictionary that contains the following:

op      {symbol}  The operation of the endpoint.
path    {string}  The path of the endpoint.
arg     {dict}    Input parameters, as defined by `params` argument to `register`.
rawArg  {dict}    Input parameters as received in the request, without parsing.
data    {any}     Request body as defined by `.com_kx_rest.reg.body`.
rawData {any}     Request body as received, after deserializing from JSON.
hdr     {dict}    Headers as received.
  • A KDB data structure (typically a dictionary or a table), which is serialized to JSON by the framework before being returned to the client
  • Result of .com_kx_rest.util.response function, which given the handler control over the HTTP status code, and content type of the response (available post release 1.0.0).
  • Result of .com_kx_rest.util.httpResponse function, which gives the handler total control over the response.
  • If there is a problem possibly with input, the handler must call .util.throw to signal an error.

.com_kx_rest.data

This function defines a data item that can be used as one of the following: - A path-parameter or query-string based input parameter (when invoked in the context of specifying params argument of .com_kx_rest.register function). - An element of an object (when invoked in the context of specifying items argument of .com_kx_rest.reg.object function).

Parameters:

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.

## ` .com_kx_rest.process`

_Process an incoming HTTP request_

```syntax
.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.process

This function processes an incoming HTTP request. The operation is determined from http-method custom header if present, otherwise value of op argument is used.

Parameters

op {symbol}     Default REST operation, used if `http-method` header is not present.
x  {list}       Incoming request - argument to `.z.ph` and `.z.pp`.

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

.z.ph:.rest.process[`GET]
.z.pp:.rest.process[`POST]

.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.