Difficulty: Beginner
Estimated Time: 10 minutes

Astra offers a REST API, which allows you to create and modify tables as well as insert, query and change data within the database. Let's take a look at this helpful Astra feature!

As a prerequisite, be sure to setup an Astra account and create a database as detailed in the Creating an Astra Database scenario.

In this scenario we'll explore the REST API. We'll create a table, insert some data and query the data. We'll use the Better Botz database we created when we set up our account. Onward...

Better Botz

ver 0.004

Code Complete

Thanks for taking a tour of Astra's REST API! For more details and elaboration of the features check out the documentation located at https://astra.readme.io/docs!

For more information and details on using the Astra REST API read the documentation at astra.readme.io.

For further reading of the work with Better Botz, check out our articles we post regularly on the Better Botz Blog.

Please give this scenario a rating (click on the stars near the top).

Astra REST API Service

Step 1 of 4

Setting up Environment Variables

In this first step, let's set up some environment variables. We'll use these variables in later steps.

Let's start with a variable that contains the Astra REST endpoint URL. Copy and paste the following command into the terminal.

export ASTRA_URL=''

Now, get the REST endpoint URL from the Astra website and paste it between the quotes.

Astra Dashboard

With the pasted URL in place, execute the export command.

We'll create variables for the database credentials. Copy and paste the following command into the terminal

export DB_USER=''

Now, enter your Astra database username between the single quotes and execute the command.

Copy and paste the following command into the terminal

export DB_PASSWORD=''

Enter your Astra database password between the single quotes and execute the command.

Next, we want to extract the base part of the URL and store it in an environment variable named $BASEURI. Execute this sed script to do that.

export BASEURI=$(echo $ASTRA_URL | sed 's/\.com.*/\.com/')

You can inspect the result of the command here.


The last environment variable we need is one that contains the database authorization token. We'll use the following command to retrieve the token and set the variable.

Want to know how this command works? This command looks complicated, so let's break it down for you.

There are actually three commands here that work together. The outer command has the following form and creates an environment variable. export TOKEN=<variable's value goes here>

There are two inner commands surrounded by $(), which causes the commands to execute and the result to be the value of the variable.

The first of the two inner commands is a cURL command to retrieve info from the Astra website. The second jq command parses the result of the cURL command and isolates the token value. The two inner commands have this form: curl \ --request POST \ --url ${BASEURI}/api/rest/v1/auth \ --header 'Content-Type: application/json' \ --data-raw '{"username":"${DB_USER}","password":"$DB_PASSWORD}"}' \ | jq -r '.authToken'

Here's an explanation of the cURL command options:
  • --request POST causes cURL to issue and HTTP POST command
  • --url ${BASEURI}/api/rest/v1/auth specifies the target of the POST command
  • --header 'Content-Type: application/json' tells cURL to use JSON syntax
  • --data-raw '{"username":"${DB_USER}","password":"${DB_PASSWORD}"}' is the JSON containing the database credentials that cURL uses to access the token
export TOKEN=$(curl --request POST --url ${BASEURI}/api/rest/v1/auth --header 'Content-Type: application/json' --data-raw "{\"username\":\"${DB_USER}\",\"password\":\"${DB_PASSWORD}\"}" | jq -r '.authToken')

Now to check that the environment variables are set and available, run this command.

printf "${GREEN}Base URI is $BASEURI${NC}\n"
printf "${GREEN}Token is $TOKEN${NC}\n"

With those set, we're ready to get started!