Difficulty: Intermediate
Estimated Time: 15 minutes

GraphQL is an open-source data query and manipulation language for APIs that allows clients to understand the data that your APIs expose and ask for only the portions they want. With GraphQL, you can create applications and services to aggregate data from multiple services or data stores. The Stargate open source project provides an API layer that allows you to expose a GraphQL API on top of any Cassandra database. Astra now offers offers a GraphQL API via Stargate, which we explore in this scenario.

We'll use the GraphQL API to:

  • Create tables and records
  • Read records from the tables
  • Update records
  • Delete records

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

GraphQL is great stuff! Let's take a look.

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

You're all set!

Thanks for taking a tour of Stargate's GraphQL API on Astra! For more details and elaboration of the GraphQL API features check out the Stargate documentation.

For more information and details on using the GraphQL 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 GraphQL API for Apache Cassandra™

Step 1 of 6

Setting up Environment Variables

Let's get coding!

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 (labeled Terminal) 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 GraphQL API access.

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

Connect using GraphQL

Step 2. Copy the export commands from the Astra web page. We'll follow the instructions in the Connect using GraphQL section of the Astra dashboard. Using the first step in the Connect using GraphQL 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 export command that you pasted (which exports the value for ASTRA_DB_PASSWORD), 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

Note: _If you look closely at the cURL command, you will observe that this is actually a REST command and not GraphQL. We will use REST to get the authorization token, but we promise that the remainder of the commands will be pure GraphQL :).

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.
printf "${GREEN}Cluster ID is $ASTRA_DB_ID${NC}\n"
printf "${GREEN}Cluster 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!