Difficulty: Beginner
Estimated Time: 10 minutes

REST stands for Representational State Transfer. The RESTful API style is a popular way of using standard HTTP commands like POST, PUT, GET, DELETE, and others to support exchange of data, using formats such as JSON. This style of interface promotes a clean separation between implementation of clients and servers.

The Stargate open source project provides an API layer that allows you to expose a REST API on top of any Cassandra database. When the Stargate REST API is added to an existing Cassandra deployment, it automatically creates HTTP endpoints that allow you to perform create, read, update, and delete (CRUD) operations on tables in your database. You can also create new database tables directly via the API.

Astra now offers offers a REST API via Stargate, which we explore in this scenario.

We'll use the Astra REST API to:

  • Create a table and a record
  • Read the record from the table
  • Update the record
  • Delete the record

As a prerequisite, be sure to setup an Astra account and create a Cassandra as a Service database at astra.datastax.com.

This is fun and easy! We'll show you how.

This scenario is also available on our datastax.com/dev site, where you can find many more resources to help you succeed with Apache Cassandra™.

Code Complete

Thanks for taking a tour of Stargate's REST API on Astra!

For more details and elaboration of the REST API features check out the Stargate documentation.

For more information and details on using the REST API on Astra read the documentation.

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

Have questions or more feedback? Send us a message.

Getting Started with Stargate REST API for Apache Cassandra™

Step 1 of 6

Setting up Environment Variables

Ok, let's get started!

New to our scenarios? Click here for three easy tips.
Tip 1 - You can click lines that begin with a triangle (like the following) to see further explanation.
Try clicking on this line. This is where you would find further explanation.

Tip 2 - To paste content into the terminal, click on the right-hand side of the screen and select Paste. Paste to terminal
Tip 3 - If a dark box has a bent arrow at the end, you can execute the command in that box by clicking on the box. The scenario will copy the command to the terminal and begin execution. Execute command
After you execute the command, the bent arrow changes to a check mark.

Thats it! You're good to go!

We'll set up some environment variables to help simplify our REST API access.

Step 1. Go to the REST Connection section of your Astra database. Login to Astra, select your database and click on the Connect tab. Then, select Connect using REST.

Connect using REST

Step 2. Copy the export commands from the Astra web page. We'll follow the instructions in the Connect using REST section of the Astra dashboard. Using the first step in the Connect using REST section, copy the commands to the clipboard by clicking the copy icon.

Copy Commands

Step 3. Paste the export commands in the terminal. You just copied several export commands to the clipboard. Paste the contents of the clipboard in the terminal, BUT DO NOT EXECUTE THE FINAL COMMAND YET

Paste Export Commands

Step 4. Set the correct value for ASTRA_DB_PASSWORD. The last command will require you to replace "<database_password>" with the password you used when you created the database. When you paste the commands, this last command will not execute, which gives you a chance to set the password.

Set Password

Step 5. Execute the final export command. Once you have set the correct value for ASTRA_DB_PASSWORD, you can execute the command by hitting Enter in the terminal.

Press Enter

Step 6. Save the authorization token in an environment variable. 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. 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 ASTRA_AUTHORIZATION_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 \ -L -X POST \ https://$ASTRA_DB_ID-$ASTRA_DB_REGION.apps.astra.datastax.com/api/rest/v1/auth \ --header 'Content-Type: application/json' \ --data '{"username":"'"$ASTRA_DB_USERNAME"'", "password":"'"$ASTRA_DB_PASSWORD"'"}' \ | jq -r '.authToken'

Here's an explanation of the cURL command options:
  • POST causes cURL to issue and HTTP POST command
  • https://$ASTRA_DB_ID-$ASTRA_DB_REGION.apps.astra.datastax.com/api/rest/v1/auth specifies the target of the POST command
  • --header 'Content-Type: application/json' tells cURL to use JSON syntax
  • --data '{"username":"'"$ASTRA_DB_USERNAME"'", "password":"'"$ASTRA_DB_PASSWORD"'"}' is the JSON containing the database credentials that cURL uses to access the token
export ASTRA_AUTHORIZATION_TOKEN=$(curl -L -X POST https://$ASTRA_DB_ID-$ASTRA_DB_REGION.apps.astra.datastax.com/api/rest/v1/auth --header 'Content-Type: application/json' --data '{"username":"'"$ASTRA_DB_USERNAME"'", "password":"'"$ASTRA_DB_PASSWORD"'"}' | jq -r '.authToken')
Step 7. Verify that we set the environment variables correctly. Here, we just want to review the values of the environment variables to make sure they are correct. You can run the following command, which prints the values in green. Astra filled in most of the values for you, but pay special attention to the password value and the token. The token should look like a random string of characters.
GREEN='\033[0;32m'
NC='\033[0m'
printf "${GREEN}DB ID is $ASTRA_DB_ID${NC}\n"
printf "${GREEN}DB region is $ASTRA_DB_REGION${NC}\n"
printf "${GREEN}Keyspace is $ASTRA_DB_KEYSPACE${NC}\n"
printf "${GREEN}Username is $ASTRA_DB_USERNAME${NC}\n"
printf "${GREEN}Password is $ASTRA_DB_PASSWORD${NC}\n"
printf "${GREEN}Authorization token is $ASTRA_AUTHORIZATION_TOKEN${NC}\n"

The environment variables are all set!