Table Of Contents

5.10. quasardb rest api

5.10.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.10.2. Quick Reference

Option Usage Default
-h, --help Show this help message  
--config-file Config file to setup the rest-api  
--cluster URI of the cluster we connect to  
--cluster-public-key-file Key file used for logging  
--log-file File we log to  
--assets-dir Directory we make publicly available  
--host IP to listen on localhost
--port Port to listen on 40080
--tls-host IP to listen on for tls localhost
--tls-port Port to listen on for tls 40493
--tls-certificate Certificate used for tls secure connection  
--tls-key Private key used for tls secure connection  
--gen-config Generate a config file.  

5.10.3. Setting up

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

Default config

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

      "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 as an encoded json string:

      "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.10.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.10.6. Options

-h, --help

Displays basic usage information.

--config-file

Config file to setup the rest-api.

--cluster

The cluster uri used for connection.

--cluster-public-key-file

The cluster public key file used for authentication through the logging phase in the dashboard. It works in parallel with a user private key.

--log-file

The file we use for logging purposes.

--assets-dir

The assets directory is made available online at the address https://host:port/index.html If you replace it the dashboard will no longer be available.

--host

IP to listen on

Default value:
localhost
--port

Port to listen on

Default value:
40080
--tls-host

IP to listen on for tls

Default value:
localhost
--tls-port

Port to listen on for tls

Default value:
40080
--tls-certificate

Certificate used for tls secure connection

--tls-key

Private key used for tls secure connection

--gen-config

Helps you generate a configuration file properly

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