Difficulty: Intermediate
Estimated Time: 15 minutes

Interested in seeing a real application leveraging Stargate APIs on DataStax Astra DB? Welcome to BattleStax, an online party game you can enjoy with your friends. Battlestax is implemented as a JAMStack app that uses Stargate, Netlify functions, Astra DB, and GitHub to demonstrate how to build and deploy an application using modern, scalable architectures.


Stargate is about giving you the API you want for your Astra DB database. In this example, we can use the Document API to save and search schemaless JSON documents in Cassandra.

Before we begin

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

Watch this video on How to Create a Database with Astra DB in 2 minutes if you need more help.

In this scenario we will:

  • Create a mock serverless REST endpoint that exposes a document API
  • Create an insertGame endpoint and connect to Astra DB
  • Run TDD tests

Let's learn how to create serverless endpoints using Netlify functions in a development environment.

Code Complete

Check out the full BattleStax Workshop!

For more information and details on using the Document API on Astra DB read the documentation, or try out this scenario to learn the basics.

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

Have questions or more feedback? Send us a message.

Create a Serverless REST Endpoint

Step 1 of 7

Setting up Environment Variables

First of all, we will need set up some environment variables to help simplify our REST API access. You must have already created an Astra database and keyspace to complete this step.

Note: For production environments, it may be preferable to configure the environment using an .env file. However, to keep things simple in this exercise, we will merely use environment variables.

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, right-click in the terminal 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.

Bonus Tip! - You can click on images to enlarge them.

Thats it! You're good to go!

Follows these steps to set the environment variables.

Step 1. Login to Astra.
Open a tab in the browser for Astra. You can login using a GitHub or Google account, or create a new Astra account.

Login to Astra

Step 2. Go to the Connection tab of your Astra DB database.
From the Astra DB dashboard, click on the database name. Then, click the Connect tab.

To connect tab

Step 3. Copy the environment variables from the Astra DB Connect tab.
From the Connect tab, click Document API from the navigation on the left. Under Step 2 of the Prerequisites, click the copy icon to copy all the export commands.

Copy the export commands

Step 4. Paste the export commands into the terminal.
Back in the Katacoda terminal, paste the contents of the clipboard at the terminal prompt. All but the last of these export commands will execute. Do NOT execute the final command yet - we need to replace <app_token> before we can execute it.

Paste export commands

Note: Do NOT execute the final export command yet!

Step 5. Find the Organization Settings.
From the Current Organization drop-down, select Organization Settings.

Find Organizational Settings

Step 6. Access Token Management.
In the left-navigation list, select Token Management.

Select Token Management

Step 7. Generate a new application token.
From the Select Role drop-down menu, select Database Administrator. Click the Generate Token button.

Generate the Token

Step 8. Copy the application token.
Click on the clipboard icon near the right edge of the token to copy the token to your clipboard. Please note that, as a security precaution, you will only be able to copy this token once. So, please take care not to overwrite the token until you have completed the next step.

Copy the token to the clipboard

Step 9. Replace <app_token> with the application token and execute the command.
Return to the Katacoda terminal. Delete <app_token> at the end of the final export command. Paste the copied token into the terminal at the end of the export command and hit enter to execute the command.

Paste the token from the clipboard

We need to set one more variable that is specific to our application.


Verify the environment variables are set correctly.


Note: A keyspace is equivalent to a namespace when using the Document API. You need to use an empty keyspace or a keyspace with only documents for this scenario.

Fantastic! The environment variables are ready to go!