4.6. REST API#

4.6.1. Requirements#

Before you can get started, please ensure that:

  • You have the latest version of the QuasarDB client library installed on your computer

  • You have access to a running QuasarDB cluster.

The rest of this document assumes you have a cluster up and running under qdb://127.0.0.1:2836.

4.6.2. Connection management#

Establishing a connection with the QuasarDB cluster is easy. You need the URI of at least one of your nodes, and the client will automatically detect all nodes in the cluster.

A QuasarDB cluster operates in either a secure or an insecure mode. If you do not know whether your cluster is running in secure mode, please ask your system administrator.

4.6.2.1. Insecure connection#

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "$USERNAME", "secret_key": "$SECRET"}' \
  http://127.0.0.1:40080/api/login

4.6.2.2. Secure connection#

In case of a secure connection, we need to provide a few additional parameters:

  • A username;

  • A user private key;

  • A cluster public key.

More information on QuasarDB’s security mechanisms can be found in our security manual.

If you do not know the values of these parameters, please ask your system administrator.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "$USERNAME", "secret_key": "$SECRET"}' \
  http://127.0.0.1:40080/api/login

4.6.3. Queries#

If you are looking for more flexible control over the kind of calculations performed on a dataset, or want to push certain computations to the cluster, QuasarDB offers an SQL-like query language for you to interact with your data. Please see our query language documentation.

In the example below, we will show you how to execute a simple query that calculates to total traded volume for the entire dataset.

curl \
  -X POST \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "query": "SELECT SUM(volume) FROM stocks" }' \
  http://127.0.0.1:40080/api/query

4.6.4. Routes#

  • api/status/liveness

    Check whether you can reach the REST API server.

    No login is necessary.

  • api/status/readiness

    Check whether you can reach the cluster from the REST API server.

    No login is necessary.

  • api/login

    Login to a secured cluster.

    The token sent back has a validity of 12hours.

{
    "username": "tintin",
    "secret_key": "SIMC1BQCOgjU7rkMoMP3gVQACA6JcxRwLhok/5bgS0J8="
}

  • Returns:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NDk0ODM1MDcsImp0aSI
              6ImJoZDlhY3NxNG1hcGloNWpiZHEwIn0.e0Jq1xYNCpE7qnXQwKhKC_Mot4NoyNPg-RSyYK4Exrg"
}

  • api/cluster

    Get basic information about the cluster disk and memory usage, the nodes and their status

{
    "diskTotal": 500695072768,
    "diskUsed": 146396606464,
    "memoryTotal": 16633151488,
    "memoryUsed": 10571653120,
    "nodes": ["127.0.0.1:2836"],
    "status": "stable"
}

{
    "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"
        }
    ]
}

4.6.5. Examples#

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

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

4.6.5.1. Default config#

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

Let’s first check that we can reach the REST API:

$> curl -k  -X GET -i http://localhost:40080/api/status/liveness
HTTP/1.1 200 OK
...

Then check that the REST API can reach the qdb cluster:

curl -k  -X GET -i http://localhost:40080/api/status/readiness

If your cluster is not running you will see:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Vary: Origin
Date: Fri, 21 Oct 2022 14:35:04 GMT
Content-Length: 34
Connection: close

{"message":"Connection refused."}

Start your cluster, make sure the URI is correct then try again.

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

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

4.6.6. Checking Access with Postman#

4.6.6.1. GET#

To check the status of the REST API server using Postman, follow these steps:

  1. Open Postman: If you don’t have Postman installed, you can download and install it from the [Postman website](https://www.postman.com/downloads/).

  2. Create a New Request: - Open Postman. - Click on “New” to create a new request. - Choose HTTP

  3. Set Request Method: - In the request details, select the HTTP request method as “GET.” You can click on the dropdown menu next to the URL field to select the method.

  4. Set Request URL: - Enter the request URL in the URL field. For example: https://127.0.0.1:40443/api/status/liveness.

  5. Send the Request: - Finally, click the “Send” button to send the GET request.

Postman will send the GET request to the specified URL, and you should receive a response from the server. In this case, you are checking whether the REST API server is live, and if it is, you should expect to receive a response with a status code of 200.

The response and any additional information will be displayed in the Postman interface, allowing you to confirm the liveness of the REST API server.

4.6.6.2. POST#

To log in to a secured cluster using Postman, follow these steps:

  1. First two steps are teh same as GET

  2. Set Request Method: - In the request details, select the HTTP request method as “POST.” You can click on the dropdown menu next to the URL field to select the method.

  3. Set Request URL: - Enter the request URL in the URL field. In your case, it would be https://127.0.0.1:40443/api/login.

  4. Set Request Headers: - Add a request header for “Content-Type” with the value “application/json.” This header specifies that the request body will contain JSON data.

  5. Set Request Body: - In the request body section, select the “raw” option. - Enter the JSON data in the request body. Your request body should look like this:

{
    "username": "tintin",
    "secret_key": "SIMC1BQCOgjU7rkMoMP3gVQACA6JcxRwLhok/5bgS0J8="
}

This JSON data includes your username and secret key for authentication.

  1. Send the Request: - Finally, click the “Send” button to send the POST request.

Postman will send the POST request to the specified URL with the provided JSON data. If your credentials are correct and the server is configured to accept them, you should receive a response.

4.6.7. Dashboard#

The dashboard is a tool that permits you to monitor your cluster in your browser.

You can easily see which nodes are active or not, and the precise statistics for each of those.

It is also possible to run queries directly through the dashboard to have some quick results.

4.6.7.1. Running#

You can access the dashboard at the same address as the qdb_rest instance (qdb_rest needs to be running), but instead of the api call you reach:

https://localhost:port

Upon opening it will open a dialog to login to the database, it is a required step if your cluster is secured.

In the other case where your cluster is not secured you can access the dashboard with:

https://localhost:40000/#anonymous

Or in the case you have no tls certificate:

http://localhost:40000/#anonymous

As for the qdb_rest it is impossible to access a secured cluster through an unsecured connection.

4.6.8. Extras: cURL Command Parameters#

Below are explanations of parameters used in the cURL command examples:

  • -X POST: Specifies the HTTP request method as POST.

  • -H “Content-Type: application/json”: Sets the Content-Type header to indicate JSON data.

  • -d ‘{“username”: “$USERNAME”, “secret_key”: “$SECRET”}’: Defines the JSON data to send in the request body with username and secret_key.

  • http://127.0.0.1:40080/example/url: The target URL for the HTTP request.

  • -H “Authorization: Bearer ${TOKEN}”: Sets the Authorization header with a bearer token. In other words, it acts as your virtual ID card. It tells the system, “I’m authorized to do this action.”

  • -d ‘{ “query”: “SELECT SUM(volume) FROM stocks” }’: Defines the JSON data to send in the request body with a SQL query.

  • -k: Disables SSL certificate verification (insecure).

  • -X GET: Specifies the HTTP request method as GET.

  • -i: Includes the HTTP response headers in the output.

  • http://127.0.0.1:40080/api/cluster/nodes/127.0.0.1:2836: The target URL for the HTTP request.

  • -sb: These flags have specific meanings: - -s: It puts the command in silent mode, meaning it won’t display progress information. It’s like running the command quietly. - -b: This flag tells cURL to store cookies received from the server. Think of it as your browser storing information for future visits.

Note: Replace ${TOKEN}, $USERNAME, and $SECRET with actual values when using these commands.