Sample Server

Introduction

This sample demonstrates using the REST framework.

$q src/sample.q

For programmatic information about all the endpoints:

$ curl 'localhost:8080/help' | jq '.'

Note: to simplify the examples, we assume .rest namespace exists which aliases .com_kx_rest:

.rest:.com_kx_rest; / Alias namespace for convenience

Sample endpoints:

GET /customers

Returns all customers.

Parameters:

Name	Datatype	Description
i	int	(Optional) Offset of first row. Default is 0.
cnt	int	(Optional) Number of rows to return. Default is 10.

Definition:

.rest.register[`get;"/customers";
  "Returns all customers";
  {take[x[`arg;`cnt]]select from customers where i>=x[`arg;`i]};
  pagingParams
  ];

Note that pagingParams is an example of a list of parameters that are commonly used together so the practice is to group them in a variable to be reusable:

pagingParams:.rest.reg.data[`i;-6h;0b;0;"Offset of first row"],
  .rest.reg.data[`cnt;-6h;0b;10;"Number of rows to return"];

Example query:

$ curl 'localhost:8080/customers?i=10&cnt=5'
[{"id":11,"name":"enfebeo"},{"id":12,"name":"plhojbe"},{"id":13,"name":"nniljhf"},{"id":14,"name":"glchmcc"},{"id":15,"name":"gkpmjca"}]

---

GET /customers.2

Version 2 of customers endpoint.

Parameters:

Name	Datatype	Description
i	int	(Optional) Offset of first row. Default is 0.
cnt	int	(Optional) Number of rows to return. Default is 10.

Definition:

.rest.register[`get;"/customers.2";
    "Returns all customers";
    {take[x[`arg;`cnt]]update newCol:1 from select from customers where i>=x[`arg;`i]};
    pagingParams
    ];

Example query:

~$ curl 'localhost:8080/customers.2?i=10&cnt=2' | jq '.'
[
  {
    "id": 11,
    "name": "enfebeo",
    "newCol": 1
  },
  {
    "id": 12,
    "name": "plhojbe",
    "newCol": 1
  }
]

---

GET /v3/customers

Version 3 of customers endpoint (showing a different way for versioning).

Parameters:

Name	Datatype	Description
i	int	(Optional) Offset of first row. Default is 0.
cnt	int	(Optional) Number of rows to return. Default is 10.

Definition:

.rest.register[`get;"/v3/customers";
    "Returns all customers";
    {take[x[`arg;`cnt]]update newCol:1, newCol2:10 from select from customers where i>=x[`arg;`i]};
    pagingParams
    ];

Example query:

~$ curl 'localhost:8080/v3/customers?i=10&cnt=2' | jq '.'
[
  {
    "id": 11,
    "name": "enfebeo",
    "newCol": 1,
    "newCol2": 10
  },
  {
    "id": 12,
    "name": "plhojbe",
    "newCol": 1,
    "newCol2": 10
  }
]

---

GET /customers/{id}

Returns one or more customer objects.

Parameters:

Name	Datatype	Description
id	int[]	One or more customer IDs

Definition:

.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"]
    ];

Example query:

$ curl 'localhost:8080/customers/10,11'
[{"id":10,"name":"fglgofj"},{"id":11,"name":"enfebeo"}]

---

GET /db

Returns table names

Parameters: none

Definition:

.rest.register[`get;"/db";
    "Retrieves list of table names";
    {tables[]};
    ()!()
    ];

Example request:

$ curl 'localhost:8080/db'
["customers","pagingParams","symbols","trades"]

---

GET /db/{table}

Queries all columns of specified table

Parameters:

Name	Datatype	Description
table	symbol	Table name
i	int	(Optional) Offset of first row. Default is 0
cnt	int	(Optional) Number of rows to return. Default is 10

Definition:

.rest.register[`get;"/db/{table}";
    "Retrieves a table";
    .tbl.getData;
    .rest.reg.data[`table;-11h;1b;`;"Table name"],
    pagingParams
    ];

Example request:

$ curl 'localhost:8080/db/trades?cnt=3' | jq '.'
[
  {
    "ts": "2021-02-19T00:00:00.000000000",
    "sym": "ftse",
    "price": 5.989167,
    "size": 745
  },
  {
    "ts": "2021-02-19T00:01:00.000000000",
    "sym": "ftse",
    "price": 0.4881728,
    "size": 362
  },
  {
    "ts": "2021-02-19T00:02:00.000000000",
    "sym": "msft",
    "price": 9.006991,
    "size": 637
  }
]

---

GET /db/{table}/{col}

Queries a subset of columns of specified table

Parameters:

Name	Datatype	Description
table	symbol	Table name
col	symbol[]	Column names
i	int	(Optional) Offset of first row. Default is 0
cnt	int	(Optional) Number of rows to return. Default is 10

Definition:

.rest.register[`get;"/db/{table}/{col}";
    "Retrieves a column subset of a table";
    .tbl.getData;
    .rest.reg.data[`table;-11h;1b;`;"Table name"],
    .rest.reg.data[`col;11h;1b;`;"Result columns"],
    pagingParams
    ];

Example query:

$ curl 'localhost:8080/db/trades/sym,size?cnt=3' | jq '.'
[
  {
    "sym": "ftse",
    "size": 745
  },
  {
    "sym": "ftse",
    "size": 362
  },
  {
    "sym": "msft",
    "size": 637
  }
]

---

GET /db/{table}/meta

Queries schema of specified table

Parameters:

Name	Datatype	Description
table	symbol	Table name

Definition:

.rest.register[`get;"/db/{table}/meta";
    "Retrieves metadata of a  table";
    {0!meta x[`arg;`table]};
    .rest.reg.data[`table;-11h;1b;`;"Table name"]
    ];

---