2.5. quasardb REST API

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

2.5.2. Quick Reference

Option	Default	Env. variable
-h, --help
--allowed-origins
-c, --cluster	qdb://127.0.0.1:2836	$QDB_CLUSTER_URI
--cluster-public-key-file		$QDB_CLUSTER_PUBLIC_KEY_FILE
--rest-private-key-file		$QDB_REST_PRIVATE_KEY_FILE
--readiness-query		$QDB_READINESS_QUERY
--tls-certificate		$TLS_CERTIFICATE
--tls-key		$TLS_PRIVATE_KEY
--tls-port	40493	$TLS_PORT
--host	localhost	$HOST
--port	40080	$PORT
--log-file	/var/log/qdb/qdb_rest.log	$QDB_REST_LOG_FILE
--assets-dir	/var/lib/qdb/assets	$QDB_REST_ASSETS_DIR
--max-in-buffer-size	131072000	$QDB_MAX_IN_BUFFER_SIZE
--parallelism-count	1	$QDB_PARALLELISM_COUNT
--pool-size	1	$QDB_POOL_SIZE
--config-file
--gen-config
-i, --interactive
-l, --local
-s, --secure

Note

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

Detailed explantion of each option can be found at Understanding options

2.5.3. Setup

2.5.3.1. No security

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: (Detailed explantion of each option can be found at Understanding options)

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

More information about dashboard can be found at: Dashboard

2.5.4. Configuration

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

Let’s dissect each part:

The openssl req command is used to generate a new certificate request and private key.

• -newkey rsa:4096 specifies that a new RSA private key with a length of 4096 bits should be generated.

• -nodes means that the private key won’t be encrypted with a passphrase (not recommended for production, but for simplification here).

• -sha512 specifies the SHA-512 hashing algorithm.

• -x509 indicates that you want to create a self-signed certificate.

• -days 3650 sets the certificate to be valid for 10 years (adjust as needed).

• -out /etc/qdb/rest-api.cert.pem specifies the output file for the certificate.

• -keyout /etc/qdb/rest-api.key.pem specifies the output file for the private key.

• -subj “/C=FR/L=Paris/O=YourCompany/CN=YourCompany” provides subject information for the certificate, such as country, location, organization, and common name.

So, when you run the provided OpenSSL command in your shell, it generates a self-signed SSL/TLS certificate and a private key. These files are essential for enabling secure HTTPS connections to your QuasarDB REST API.

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.

2.5.4.2. Secured cluster config

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

You should find them 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”
rest_private_key_file	/etc/qdb/qdb_rest_private.key	“C:\Program Files\quasardb\conf\qdb_rest_private.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",
  "rest_private_key_file": "/etc/qdb/qdb_rest_private.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"
}

2.5.4.3. Generating a User Private Key and Login

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

Let’s dissect each part:

1. -u tintin: This option specifies the username for which you want to generate the private key. Replace “tintin” with the actual username for which you want to create a key.

2. -s tintin.private: This option indicates the output file where the generated private key will be stored. In this example, it’s named tintin.private. You can choose a different filename if you prefer.

3. -p users.cfg: This option may specify a configuration file (e.g., users.cfg) that contains additional user-related settings.

When you run the provided command in your shell, it generates a user-specific private key file named tintin.private (or the name you specify).

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`

Let’s break down each part of the Curl command:

• -H Origin: http://0.0.0.0:3449: Here, we’re adding an HTTP header to the request. It specifies the “Origin” header with the value ‘http://0.0.0.0:3449’. This header is used to indicate the origin (source) of the request.

• --data-binary @tintin.private: This part sends data in the request body. It tells Curl to use the content of the file “tintin.private” as the request body data. The “@” symbol indicates that we’re reading the data from a file.

For more detailed information refer to Extras: cURL Command Parameters.

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

2.5.5. Understanding options

• --allowed-origins: Specify which websites or applications can access your QuasarDB REST API from different origins (e.g., different domains). Useful for controlling cross-origin access.

• -c, --cluster: Define the address (URI) of the QuasarDB cluster that the REST API will connect to. Think of it as telling the REST API where your database is located.

• --cluster-public-key-file: This is a security feature. It points to the file containing the public key used for securing communication with the QuasarDB cluster.

• --rest-private-key-file: Similar to the previous option but focused on a private key used for readiness checks. Helps ensure that the cluster is ready to handle requests.

• --readiness-query: Customize the query that checks if your QuasarDB cluster is ready for requests. This query confirms that the cluster is fully operational.

• --tls-certificate: If you want to secure your REST API with HTTPS (secure web connections), this option points to the TLS (formerly SSL) certificate to use for encryption.

• --tls-key: This complements the previous option by specifying the private key required for secure communication.

• --tls-port: If you’re securing your API, this option sets the port for secure connections.

• --host: Define the IP address on which the REST API should listen. By default, it’s set to “localhost” (meaning it listens only on your local machine).

• --port: Set the port on which the REST API listens for incoming connections. Default is 40080 for insecure connections.

• --log-file: Specify the file path where log messages from the REST API will be stored.

• --assets-dir: Define the directory where the REST API should look for additional assets (e.g., web page files).

• --config-file: Point to a configuration file (in JSON format) to set up the REST API with predefined settings.

• --gen-config: Generate a new configuration file interactively to set up the REST API. Helpful if you want to create a custom configuration file.

• -i, --interactive: Activate interactive mode when generating a configuration file. This allows you to make choices step by step.

• -l, --local: Enable local mode, which may be useful for development and testing.

• -s, --secure: Activate security defaults. Useful for ensuring secure communication with the QuasarDB cluster.

In this section, we will explore three newly added options that provide additional control and customization for the QuasarDB REST API server. These options are:

--max-in-buffer-size

This option decides the largest chunk of data that can be received from the server in one go. It sets the maximum size for incoming data.

Usage: Use it when you want to limit the amount of memory used for incoming data.

Use Case:

You have a specific use case where you expect large data payloads from the server. By increasing the –max-in-buffer-size to, let’s say, 262,144,000 bytes (or 250 MB), you can efficiently handle and process larger data chunks without encountering buffer overflow issues.

--parallelism-count

The –parallelism-count option is a setting that enhances the speed of each individual query.

Usage: Use it to speed up query execution;

Use Case:

When this value is set to 16, for instance, it means there will be 16 separate threads, each working on processing the query concurrently. This increase in parallelism count can significantly accelerate the execution of each individual query. However, it’s important to note that the parallelism comes at the cost of some additional overhead.

--pool-size

This option comes into play when you’re running more than one query in parallel.

Usage: It allows you to regulate the maximum number of connections that your application can create.

Use Case:

In a scenario where you have several concurrent requests, you can use –pool-size to manage resource allocation effectively. This ensures that resources are distributed fairly among the parallel requests.