1.5. quasardb REST API¶

1.5.1. Introduction¶

The quasardb rest api, qdb_rest, provides a way to communicate with a cluster in the form of json objects.

Notably it can run queries and translate them to json.

1.5.2. Quick Reference¶

Option

Usage

Default

Env. variable

-h, --help

Show this help message

--allowed-origins

Allowed origins for cross origins

-c, --cluster

URI of the cluster we connect to

qdb://127.0.0.1:2836

$QDB_CLUSTER_URI

--cluster-public-key-file

Key file used for cluster security

$QDB_CLUSTER_PUBLIC_KEY_FILE

--tls-certificate

The tls certificate to use

$TLS_CERTIFICATE

--tls-key

The tls private key to use

$TLS_PRIVATE_KEY

--tls-port

The tls port to listen on

40493

$TLS_PORT

--host

The IP to listen on

localhost

$HOST

--port

The port to listen on

40080

$PORT

--log-file

The path to the log file

/var/log/qdb/qdb_rest.log

$QDB_REST_LOG_FILE

--assets-dir

The path to the assets directory

/var/lib/qdb/assets

$QDB_REST_ASSETS_DIR

--config-file

Config file to setup the rest api

--gen-config

Generate a config

-i, --interactive

Switch on interactive mode for gen-config

-l, --local

Switch on local mode

-s, --secure

Switch on security default parameters

Option	Usage	Default	Env. variable
`-h`, `--help`	Show this help message
`--allowed-origins`	Allowed origins for cross origins
`-c`, `--cluster`	URI of the cluster we connect to	qdb://127.0.0.1:2836	$QDB_CLUSTER_URI
`--cluster-public-key-file`	Key file used for cluster security		$QDB_CLUSTER_PUBLIC_KEY_FILE
`--tls-certificate`	The tls certificate to use		$TLS_CERTIFICATE
`--tls-key`	The tls private key to use		$TLS_PRIVATE_KEY
`--tls-port`	The tls port to listen on	40493	$TLS_PORT
`--host`	The IP to listen on	localhost	$HOST
`--port`	The port to listen on	40080	$PORT
`--log-file`	The path to the log file	/var/log/qdb/qdb_rest.log	$QDB_REST_LOG_FILE
`--assets-dir`	The path to the assets directory	/var/lib/qdb/assets	$QDB_REST_ASSETS_DIR
`--config-file`	Config file to setup the rest api
`--gen-config`	Generate a config
`-i`, `--interactive`	Switch on interactive mode for gen-config
`-l`, `--local`	Switch on local mode
`-s`, `--secure`	Switch on security default parameters

Note

The ‘-‘ or ‘- -‘ shall be replaced with ‘/’ on windows.

1.5.3. Setting up¶

Setup should be easy, and we tried to do just that!

When you want no security at all you can just use the default configuration file.

Your quasardb daemon should run with security set to false. If it’s not launched yet, run it with:

/path/to/qdbd --security=false

The default configuration for qdb_rest should look like this: (Don’t worry we’ll introduce every parameter afterward)

{
  "allowed_origins": [],
  "cluster_uri": "qdb://127.0.0.1:2836",
  "cluster_public_key_file": "",
  "tls_certificate": "",
  "tls_key": "",
  "tls_port": 40493,
  "host": "localhost",
  "port": 40080,
  "log": "qdb_rest.log",
  "assets": "assets"
}

And you can run the rest api with:

/path/to/qdb_rest --config-file my-config-file.json

Congrats you can now access the dashboard and the api.

1.5.3.1. https config¶

Let’s go a bit more into the details, you have two parameters to enable the https access of the rest api.

Assuming you have installed QuasarDB with default options, you should find the files at the following paths depending on your platform.

Parameter	Unix path	Windows path
tls_certificate	/etc/qdb/qdb_rest.cert.pem	“C:\Program Files\quasardb\conf\qdb_rest.cert.pem”
tls_key	/etc/qdb/qdb_rest.key.pem	“C:\Program Files\quasardb\conf\qdb_rest.key.pem”

These files should have been generated during the installation, if not you can generate them with letsencrypt or openssl.

An example with openssl:

openssl req -newkey rsa:4096 -nodes -sha512 -x509 -days 3650 -nodes -out /etc/qdb/rest-api.cert.pem -keyout /etc/qdb/rest-api.key.pem -subj "/C=FR/L=Paris/O=YourCompany/CN=YourCompany"

Your new configuration on a unix system:

{
  "allowed_origins": [],
  "cluster_uri": "qdb://127.0.0.1:2836",
  "cluster_public_key_file": "",
  "tls_certificate": "/etc/qdb/qdb_rest.cert.pem",
  "tls_key": "/etc/qdb/qdb_rest.key.pem",
  "tls_port": 40493,
  "host": "localhost",
  "port": 40080,
  "log": "qdb_rest.log",
  "assets": "assets"
}

You can now access the https dashboard and the https api.

1.5.3.2. Secured cluster config¶

For a secured cluster you will need another parameter the cluster_public_key_file, and the https configuration just described.

You should find it at the following paths depending on the platform where your quasardb daemon is running.

Parameter	Unix path	Windows path
cluster_public_key_file	/usr/share/qdb/cluster_public.key	“C:\Program Files\quasardb\share\cluster_public.key”

If you do not have one, you can generate it with the quasardb cluster key generator tool

/usr/local/bin/qdb_cluster_keygen -p cluster.public -s cluster.private

Your final configuration on a unix system:

{
  "allowed_origins": [],
  "cluster_uri": "qdb://127.0.0.1:2836",
  "cluster_public_key_file": "/usr/share/qdb/cluster_public.key",
  "tls_certificate": "/etc/qdb/qdb_rest.cert.pem",
  "tls_key": "/etc/qdb/qdb_rest.key.pem",
  "tls_port": 40493,
  "host": "localhost",
  "port": 40080,
  "log": "qdb_rest.log",
  "assets": "assets"
}

!! Stop whatever you’re doing right now what follows is important!

Since we run a secured cluster you will need to login to it.

We use a token based system to access the cluster through the API.

So get your user private key file ready. If you do not have one, you can generate it with the quasardb user adder program like so

qdb_user_add -u tintin -s tintin.private -p users.cfg

To login through the API, you just need to send your private key file information to the api/login route.

In the shell with curl it would look like:

TOKEN=`curl -k -H 'Origin: http://0.0.0.0:3449'  -H "Content-Type: application/json" -X POST --data-binary @tintin.private https://127.0.0.1:40443/api/login`

Now the $TOKEN variable contains the token you will need to use the api.

1.5.4. Routes¶

api/login

Login to a secured cluster.

The token sent back has a validity of 12hours.
Type: POST

Content-Type: application/json

URL structure: https://127.0.0.1:40443/api/login
Body, content of your private user security key file:
{"username":"tintin","secret_key":"SIMC1BQCOgjU7rkMoMP3gVQACA6JcxRwLhok/5bgS0J8="}
Returns:
{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NDk0ODM1MDcsImp0aSI6ImJoZDlhY3NxNG1hcGloNWpiZHEwIn0.e0Jq1xYNCpE7qnXQwKhKC_Mot4NoyNPg-RSyYK4Exrg"}

api/cluster
Get basic information about the cluster disk and memory usage, the nodes and their status
- Type: GET
- Content-Type: application/json
- URL structure: http://127.0.0.1:40080/api/cluster
- Returns:
  {"diskTotal":500695072768,"diskUsed":146396606464,"memoryTotal":16633151488,"memoryUsed":10571653120,"nodes":["127.0.0.1:2836"],"status":"stable"}

api/nodes/$id

Get basic information about the node disk and memory usage. The $id being the uri of the node.
Type: GET

Content-Type: application/json

URL structure: http://127.0.0.1:40080/api/nodes/127.0.0.1:2836
Returns:
{"cpuTotal":174985330000,"cpuUsed":59013680000,"diskTotal":500695072768,"diskUsed":146396614656,"id":"127.0.0.1:2836","memoryTotal":16633151488,"memoryUsed":10715885568,"os":"Linux 4.15.0-44-generic","quasardbVersion":"3.2.0"}

api/query

Run a query on the cluster.
Type: POST

Content-Type: application/json

URL structure: http://127.0.0.1:40080/api/query
Body, the query you wish to run:
{"query": "SELECT * FROM example"}
Returns:
{"tables":[{"columns":[{"data":["2017-01-01T01:00:00+01:00","2019-02-05T14:24:16+01:00","2019-02-06T09:12:57+01:00"],"name":"timestamp"},{"data":[1234,1234,1234],"name":"my_int"}],"name":"example"}]}

1.5.5. Examples¶

In this section we will show you end to end usage with curl requests.

1.5.5.1. Default config¶

Here we assume you have a default configuration and both qdb_rest and qdbd servers running.

Even tho you don’t need a user on the qdbd server, you will need to login to the qdb_rest api.

Doing so will give you a token you can re-use, it’s linked to a qdb_handle that stays connected for the validity of the token.

Create a file, named empty.private, with the following content:

{"username": "","secret_key": ""}

You can now login with:

TOKEN=`curl -k -H "Content-Type: application/json" -X POST --data-binary @empty.private http://127.0.0.1:40080/api/login`

If you want to know the status of the cluster and its nodes, you can type:

curl -k -H "Authorization: Bearer ${TOKEN}" -i http://localhost:40080/api/cluster

To check a simple node status you can use:

curl -k -H "Authorization: Bearer ${TOKEN}" -i http://127.0.0.1:40080/api/cluster/nodes/127.0.0.1:2836

Finaly we will show a basic example for queries.

First we will add some data with:

curl -k -H "Authorization: Bearer ${TOKEN}" -sb -X POST -H "Content-Type: application/json" -d '"INSERT INTO example ($timestamp, my_int) VALUES (now, 1234)"' http://127.0.0.1:40080/api/query

And then query it:

curl -k -H "Authorization: Bearer ${TOKEN}" -sb -X POST -H "Content-Type: application/json" -d '"SELECT * FROM example"' http://127.0.0.1:40080/api/query

1.5.5.2. Secured config¶

There are two changes for a secured cluster, the login step, and the address we want to reach.

For this step you will need a user private key file, if you do not have one, you can generate it with the quasardb user adder program like so:

qdb_user_add -u tintin -s tintin.private -p users.cfg

You can now login with:

TOKEN=`curl -k -H "Content-Type: application/json" -X POST --data-binary @tintin.private https://127.0.0.1:40443/api/login`

Note the https at the beginning of the address.

You are now able to do every other call to the api routes as described before, just add the https and your generated token will do the rest.

1.5.6. Options¶

-h, --help¶: Displays basic usage information.

--allowed-origins¶: Allowed origins for cross origins

-c, --cluster¶

URI of the cluster we connect to

Default value:: qdb://127.0.0.1:2836
Env. variable:: $QDB_CLUSTER_URI

--cluster-public-key-file¶

Key file used for cluster security

Default value (with secure option):: unix: /usr/share/qdb/cluster_public.key

windows: C:/Program Files/quasardb/share/cluster_public.key
Env. variable:: $QDB_CLUSTER_PUBLIC_KEY_FILE

--tls-certificate¶

The certificate to use for secure connections

Default value (with secure option):: unix: /etc/qdb/qdb_rest.cert.pem

windows: C:/Program Files/quasardb/conf/qdb_rest.cert.pem
Env. variable:: $TLS_CERTIFICATE

--tls-key¶

The private key to use for secure conections

Default value (with secure option):: unix: /etc/qdb/qdb_rest.key.pem

windows: C:/Program Files/quasardb/conf/qdb_rest.key.pem
Env. variable:: $TLS_PRIVATE_KEY

--tls-port¶

The port to listen on for secure connections, defaults to a random value

Default value:: 40493
Env. variable:: $TLS_PORT

--host¶

The IP to listen on

Default value:: localhost
Env. variable:: $HOST

--port¶

The port to listen on for insecure connections, defaults to a random value

Default value:: 40080
Env. variable:: $PORT

--log-file¶

The path to the log file

Default value:: unix: /var/log/qdb/qdb_rest.log

windows: C:/Program Files/quasardb/log/qdb_rest.log
Env. variable:: $QDB_REST_LOG_FILE

--assets-dir¶

The path to the assets directory you want to be published alongside the rest api

Default value:: unix: /var/lib/qdb/assets

windows: C:/Program Files/quasardb//assets
Env. variable:: $QDB_REST_ASSETS_DIR

--config-file¶: Config file to setup the rest api

--gen-config¶: Generate a config

-i, --interactive¶: Switch on interactive mode for gen-config, does nothing if gen-config is not set

-l, --local¶: Switch on local mode

-s, --secure¶: Switch on security default parameters (tls + cluster security)

Previous Next