Welcome to the Build API and Microservices with Apache Cassandra workshop! In this two-hour workshop, the Developer Advocate team of DataStax presents the process and the basic tenets of building a REST API (which is the foundation of microservices) with data backed by Apache Cassandra.
This session is part of the 4-week bootcamp for you to learn anything you need to develop great applications for Apache Cassandra. Each Session can be followed as standalone and this one is no different. It is strongly recommended that you complete weeks 1,2,3 to get the most of this week.
It doesn't matter if you join our workshop live or you prefer to do at your own pace, we have you covered.
For the hands-on part of this workshop, we will use Astra DB, a Database-as-a-Service built on Cassandra and delivered by DataStax.
In this repository, you'll find everything you need for this workshop:
- Materials used during presentations
- Hands-on exercises
- Workshop video (Recording in progress)
- Discord chat
- Questions and Answers
- Homework Form
- Connect to your Astra DB instance
- Create Astra Token
- Run the TodoApplication
- Launch Gitpod
- Know you Gitpod
- Rest Api with Apache Cassandra
- Setup for the applications
- Badges and Homework
✨ Please visit https://astra.datastax.com to create your free Astra DB instance, required for today's hands-on exercises! 🔥 More details here on how to proceed.
If you attended previous weeks, you will have your Astra DB account already.
✅ If your database has the status
Standbythen it needs to be resumed before going on.
Show me how to resume my database.
✅ Next, make sure you have a keyspace, called
todos, if not please add it. then skip to Section 2.
Show me how to add a keyspace!
If you are new to Astra DB, please read on.
ASTRA DB is the simplest way to run Cassandra with zero operations at all - just push the button and get your cluster. No credit card required, $25.00 USD credit every month, roughly 5M writes, 30M reads, 40GB storage monthly - sufficient to run small production workloads.
✅ Register (if needed) and Sign In to Astra DB https://astra.datastax.com: You can use your Github, Google accounts or register with an email.
Make sure to chose a password with minimum 8 characters, containing upper and lowercase letters, at least one number and special character
Choose the "Start Free Now" plan, then "Get Started" to work in the free tier.
You will have plenty of free initial credit (renewed each month!), roughly corresponding to 80 GB of storage and 20M read/write operations.
If this is not enough for you, congratulations! You are most likely running a mid- to large-sized business! In that case you should switch to a paid plan.
(You can follow this guide to set up your free-tier database with the $25 monthly credit.)
-
For the database name - use
workshops. While Astra DB allows you to fill in these fields with values of your own choosing, please follow our recommendations to ensure the application runs properly. -
For the keyspace name - use
todos. Please stick to this name, it will make the following steps much easier (you have to customize here and there otherwise). In short:
| Parameter | Value |
|---|---|
| Database name | workshops |
| Keyspace name | todos |
-
For provider and region: Choose any provider (either GCP, AWS or Azure). Region is where your database will reside physically (choose one close to you or your users).
-
Create the database. Review all the fields to make sure they are as shown, and click the
Create Databasebutton.
You will see your new database as Pending in the Dashboard; the status will change to Active when the database is ready. This will only take 2-3 minutes
(you will also receive an email when it is ready).
We need to create a token that we will use as our credentials. The token does not expire so if you already have one you can reuse it.
✅ Step 2a: Generate Token
Following the Manage Application Tokens docs create a token with Database Administrator roles.
-
Go the
Organization Settings -
Go to
Token Management -
Pick the role
Database Admnistratoron the select box -
Click Generate token
👁️ Walkthrough
This is what the token page looks like. You can now download the values as a CSV since you will need those values very soon.
Notice the clipboard icon at the end of each value.
-
Client Id:We will use it as a username to connect to Astra. -
Client Secret:We will use it as a password to connect to Astra. -
appToken:It can be used as an api token Key to interact with APIs. (we won't be using this in today's workshop)
To know more about roles, tokens, etc. you can look at this video.
Note: Make sure you don't close the window accidentally or otherwise - if you close this window before you copy the values, the application token is lost forever. They won't be available later for security reasons. You'll have to create a new application token
We are now set with the database and credentials. Let's get started!
TodoMVC is a fabulous community contribution that helps developers compare frameworks on the basis of actual project code, not just claims and anecdotes. TodoMVC is an immensely valuable attempt at a difficult problem - providing a structured way of comparing JS libraries and frameworks.
✅ Step 1a. Visit TodoMVC.com to discover what we are building today : We want you to visualize the application (if you're building a brand new app you might create wire frame diagrams, for example) before we start coding. We already have a working application -so please browse http://todomvc.com/. You will see that there are multiple implementations, feel free to pick one of those and test it live in your browser.
Todo-Backend is an example to showcase backend tech stacks. The Todo-Backend project defines a simple web API spec for managing a todo list. Contributors implement that spec using various tech stacks. Those implementations are cataloged below. A spec runner verifies that each contribution implements the exact same API, by running an automated test suite which defines the API.
There are multiple free implementations available. Some implementations provide endpoints to be tested in heroku. Heroku provides free hosting. With Heroku The application will be inactive until you access the endpoint. Due to this it will take 30s (or more) for the first person hitting the endpoint to wake up the application. Among the available free endpoints we can recommend:
#1: https://todo-back-springboot220-java12.herokuapp.com/todos#2: https://todo-quarkus.herokuapp.com/todos#3: https://todo-backend-micronaut.herokuapp.com/todos
Please be patient if you only see an empty JSON output [] and refresh the browser until you see some output.
You should see the following or similar output in a JSON enabled browser.
👁️ Expected output
✅ Step 1b. Test TodoBackEnd Spec Runner : Locate the spec runner and use one of the endpoints listed above to evaluate if API matches the requirements. To do so copy-paste one URL and click Run Tests.
Pick any one from listed below:
👁️ Expected output
Note: During the live stream there will be dozens of people testing the same endpoints. It is possible that we could hit some slowness or issues with race conditions.
✅ Step 1c. Test TodoBackEnd Web Client : todoBackend.com provides a client to work with the API. As before pick one of the endpoints listed before and try the client.
Pick one of the three from below:
👁️ Expected output
Our mission in the next hour is to implement the backend API and store data into Apache Cassandra™. We have you covered by providing the skeleton of the application.
Gitpod is an IDE 100% online based on VS Code. To initialize your environment simply click on the button below (CTRL + Click to open in new tab) You will be asked for your github account, as needed.
👁️ Expected output
The screenshot may be slightly different based on your default skin and a few edits in the read me.
That's it. Gitpod provides all tools we will need today including for respective languages.
You may safely ignore the error output at the end of the terminal window.
👁️ Expected output
Although GitPod terminal might seem to be available, the setup might still be ongoing. Wait for a few minutes before entering commands in the GitPod terminal window.
You are not going to run any command in this step but it's a great idea to take a moment and familiarize yourself with Gitpod. These steps provides some details for just that. Take a tour around and get comfortable.
Take a moment to read this entire section since it'll help you with the rest of the workshop as you'll be spending most of your time in Gitpod. If you're familiar with Gitpod, you can easily skip this entire section.
The extreme left side has the explorer view(1). The top left, middle to right is where you'll be editing files(2), etc. and the bottom left, middle to right is what we will refer to as the Gitpod terminal window(3) as shown below.
👁️ Expected output
You can always get back to the file explorer view whenever by clicking on the hamburger menu on the top left followed by View and Explorer as shown below.
At the top right of the terminal window is a + sign which allows you to create multiple shells. Familiarize yourself since we will be using cql in one of the shells.
You may encounter the following at different steps and although this may not be applicable right away, the steps are included in advance and summarized here so that you can keep an eye out for it. Different paths and different environments might be slightly different although Gipod levels the playing field a bit.
You can allow cutting and pasting into the window by clicking on Allow as shown below.
Or allow ports to be opened by just exiting windows that are informational messages about ports like below.
OPTIONAL: In Gitpod, If you prefer "Dark Mode" you can set it in Preferences as shown below.
To run the application(s) you need to provide the database credentials.
Note down the values of Client Id and Client Secret from values noted earlier that we will subsequently use for username and password in the respective language in a later step.
This next step is probably the most involved step in the entire workshop. The goal of this step is to get the customized connect bundle into Gitpod. One of the several ways of doing this is as follows.
Start with the Astra DB dashboard and for the database workshops,
- Click on
Connecttab. - Click on Connect using any of the drivers
Node.js(javascript),PythonorJava. - Click on
Download Bundle. - Click on
Secure Connect Bundleto be able to copy the link locally.
as shown below.
Locate the file locally in the finder/explorer window. Drag and drop the file into the Gitpod explorer window (on the left side, making sure that the cursor, indicating the drop, is positioned in the Gitpod explorer window as shown below and on bottom right as shown below.
In the Gitpod terminal window, verify that you dropped the right file and at the top level directory
ls -l /workspace/bootcamp-fullstack-apps-with-cassandra/secure-connect-workshops.zipIf you get a message cannot access or the file size is not roughly 12K, something may have gone wrong in the process and you need to repeat this step (step 5b).
👁️ Expected output
-rw-r--r-- 1 gitpod gitpod 12261 Jan 12 23:34 /workspace/bootcamp-fullstack-apps-with-cassandra/secure-connect-workshops.zip
TADA your application is configured we can finally play with some code.
We have provided some convenience scripts to setup the credentials across all the languages.
As a first step cd to the week4-api-microservices sub-directory with the following command.
cd week4-api-microservicesLet's start by issuing the following command.
cp .env.sample .envOpen this file and update it by entering the ASTRA_USERNAME (Client Id) and ASTRA_PASSWORD (Client Secret) values. Values are not shown here. You obtained this in an earlier step.
You may issue the following command in the GitPod terminal window.
gp open .env
You are almost ready to start coding. The next step is to run the convenience script which updates the connection files that you'll be using with the appropriate values. Run the following command
./plugastracredsA BIG NOTE OF CAUTION: It's not a good practice to include username, password and other secrets in the source file. Don't ever git commit with clear case passwords, etc. This is done purely for convenience of getting started.
✅ Step 6d: Verify cql access from Gitpod
Invoke cqlsh as shown below (far right top corner of Gitpod terminal window).
If you completed the earlier steps properly, you should be dropped into the CQL shell as shown below.
Run the following command from the CQL shell of the Gitpod terminal window.
describe keyspaces;👁️ Expected output
system_virtual_schema system_auth datastax_sla todos
todolist system_views data_endpoint_auth
system_schema system system_traces
FXHtFByhHAjqNjdcLgZNYEll@cqlsh> We will refer to this as the CQL shell (cqlsh) and the original shell as the Gitpod terminal (bash ..). You can click on those tabs to switch between the shells. The image below shows clicking back on the bash shell.
OPTIONAL: You coud also split terminal and have both the bash and cqlsh side-by-side as shown below rather than clicking back on the respective tabs.
TADA! Now you're really done done with the setup and ready to start coding.
Exercises will be different for each language. Pick the language you feel the most confortable with with and JUMP to the respective README.
| Sections | Material Description |
|---|---|
 |
Exercises with Java |
 |
Exercises with Javascript |
 |
Exercises with Python |
You might be eligible for these badges when you attend workshops and complete the requirements.
To complete the workshop and get a verified badge, follow these simple steps:
- Watch the workshop live or recorded. Pick a language and run through the exercises.
- Write a new exercise/test: Update the api and service layers code to offer a new endpoint to get only completed tasks for a user.
- Submit the Homework through this form and attach the screenshots above.
- Give us a few days to review your submission and relax: your well-earned badge will soon land in your mailbox!
Sincerely yours, The DataStax Developers THE END.