Table Of Contents

5.12. quasardb REST API

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

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

Note

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

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

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.

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.

5.12.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"}]}
      

5.12.5. Examples

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

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

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.

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

arrow_backPrevious
5.11. quasardb for Excel
Next arrow_forward
5.13. quasardb dashboard