Quarkus for Architects who Sometimes Write Code - Being Persistent - Part 02

Note: This is part two of a three part post. In this post we’ll use Postman to interact with the Cassandra instance that we created in the first post.

Make sure you have completed part 1 - Quarkus for Architects who Sometimes Write Code - Being Persistent - Part 01

In the next post, we’ll finally get around to writing a Quarkus app. But today, we are going to use the Stargate Document API to get a feel for what the interaction will be like when we write a Quarkus app.

Make sure your OpenShift cluster is running

Note: If your OpenShift cluster that you installed the K8ssandra operator into is not running, start it now:

From a terminal run:

   crc start

This will take a few minutes to restart, but you can go ahead and get Postman set up in the mean time. Leave this terminal window open so you can see the progress.

Configure Postman

I have created a Postman collection for you to use in this exercise. If you don’t have postman, now is a good time to go get it: https://www.postman.com/downloads/

1. Once you have Postman installed, go ahead and start it.

2. Now, we’re going to import a Postman collection and an environment.

   Postman collections allow you to create and save API calls and tests. An environment allows you to store variable configurations for the API calls and tests. There’s a lot more to it than that, but that’s what we’re going to need for this exercise.

   1. From the main Postman screen, click on the Import button that is in the top left portion of the screen:

      

   2. You should now see the Import dialog. Select the Link option from the list at the top of the Import window.

      

   3. Past the following URL into the text box under Enter a URL, then click Continue:

      https://raw.githubusercontent.com/cgruver/k8ssandra-blog-resources/main/postman/book-catalog-01.postman_collection.json

      

   4. Click Import to import the collection:

      

   5. Repeat the above steps with the following URL to also import the Envrionment that I prepared for you:

      https://raw.githubusercontent.com/cgruver/k8ssandra-blog-resources/main/postman/book-catalog-01.postman_environment.json

      

Take some time to explore the collection and environment. You can access them via the left-hand vertical nav bar.

Add Credentials to Environment and Activate the Environment

1. Next, we need credentials to access Cassandra. We’re going to bypass creating additional users in Cassandra for this exercise and just use the super-user account that was automatically generated for us.

   The auto-generated credentials are stored in a secret that is in the k8ssandra-operator namespace. To retrieve it, first log into your crc OpenShift instance:

   1. Open a terminal and set the crc environment:

      ~ % eval $(crc oc-env)
      

   2. Retireve the login command and credentials:

      ~ % crc console --credentials
      

      You should see output similar to:

      To login as a regular user, run 'oc login -u developer -p developer https://api.crc.testing:6443'.
      To login as an admin, run 'oc login -u kubeadmin -p 3QxJ6-P5Z2c-DD7as-zfmfI https://api.crc.testing:6443'
      

   3. Copy the command to login as kubeadmin and run it:

      ~ % oc login -u kubeadmin -p 3QxJ6-P5Z2c-DD7as-zfmfI https://api.crc.testing:6443
      

      You should see output similar to:

      Login successful.
      
      You have access to 68 projects, the list has been suppressed. You can list all projects with 'oc projects'
      
      Using project "default".
      

   4. Now grab the contents of the secret created for the Cassandra credentials:

      echo $(oc -n k8ssandra-operator get secret k8ssandra-cluster-superuser -o jsonpath="{.data.password}" | base64 -d)
      

      Copy the resulting string into your clipboard. We’re going to add it to our Postman environment.

2. Add the cassandra super-user password to the Postman Environment:

   Note: I know I don’t have to say this… but I’m going to anyway… You should NEVER put production credentials into your Postman environment. This is a development tool. While the values that we’re going to be using are not persisted, it’s still sitting there on your machine in plain text for the duration of your session.

   OK, with that disclaimer out of the way, go ahead and open the Environment that I prepared for you:

   

   Note that there are two columns of values for each key. The left column of values, called INITIAL VALUE, is persisted as part of the collection. Never put anything sensitive there. It will be saved in plain-text. The right hand column of values, called CURRENT_VALUE, is ephemeral. It lasts as long as your postman session, and can be dynamically changed by your Postman tests or scripts. We’ll see an example of that with the value for AUTH_TOKEN token. I still wouldn’t put anything sensitive here, but that’s up to you. :-)

   Now, paste the value for the k8ssandra-cluster-superuser password in the row named auth_password. Paste it into the CURRENT VALUE column.

   

3. Finally, activate the environment for this session by selecting Book Catalog Stargate Env from the environment drop down in the top right had corner of Postman:

   

Use Postman To Interact with Cassandra via the Stargate Document API

Now let’s use Postman to put some data into our new Cassandra cluster, and query it.

Expand the list of prepared calls in the Book Catalog - Blog Post collection:

1. Select the Collections button at the top left of the Postman window.

2. Expand the Book Catalog - Blog Post collection.

3. Expand the Stargate Document API folder.

   

We’re going to pretty much hit these API invocations from the top down.

The results will be:

1. Create an Authentication Token and store it in the Postman environment

2. Create a Document Namespace

3. Create a Collection to hold Documents

4. Add information about 2 books to the Collection as Documents

5. Search for a book information document by ISBN10 and ISBN13

   We’ll see that we get back one document that matches the search.

6. Search for book information by Author

   We’ll see that we get back a list of documents.

7. Delete the Collection, so we don’t leave garbage sitting around.

Now, let’s dive in:

Put Some Data in Cassandra

1. The first step is to authenticate with Cassandra and get a Token:

   Select create-auth-token and click Send:

   

   Note: You will likely see a failure. Click on Disable SSL Verification. Your OpenShift Local instance is using a self-signed cert, and Postman does not pick up certs from your local keystore. It has its own. You can add the cert to Postman’s local store if you like, but the crc cert will change every time you destroy it and create a new cluster.

   

   Now, click Send again, and you should see an authToken returned:

   

2. Take a moment to click over to the Book Catalog Stargate Env environment, and notice that the authToken has been stored in the CURRENT VALUE column for the AUTH_TOKEN key:

   

3. Now, go back and select Create home_library NameSpace from the collection

   Click Send and notice the successful creation of your NameSpace:

   Note: You can see the payload submitted in POST or PUT calls by clicking on body right under the URL. You can toggle through those tabs to see Params, Headers, etc…

   

   The response for this call will be an empty 201 if it is successful.

4. Repeat with the Create book_catalog Collection:

   

5. Now that we have a collection in a namespace, let’s add some data:

   Select Save Thief Of Time and click Send:

   

   Take a look at the body of the request. It represents a Book Info document. We’ll turn this into code when we build the Quarkus app.

   Note also that we are using the PUT verb. If we use POST cassandra will assign the document id for us as a UUID. Using PUT allows us to create our own ID. PUT can also be used to update an existing document.

6. Add the second book info document by selecting Save Wyrd Sisters and click Send:

   

At this point we have inserted two documents into our collection. Behind the scenes, Stargate has interacted with Cassandra to persist this data and perform some optimizations on it for query.

This is really where the power of Stargate is going to come into play. As a developer, we are going to be abstracted away from the nuances of Cassandra data modeling and optimization. I’m fairly new to this, so I’m sure there are plenty of tradeoffs, but the simplicity can’t be beat.

So, let’s query our data!

Query The Data That We Persisted

Note: At some point your AUTH TOKEN may expire. If you get an authentication failure, just hit Send on the create-auth-token call in the collection. This will refresh your token.

1. Select Get by isbn13 from the collection:

   

   Take a look at the URL. Note the query parameter:

   where={"identifiers.isbn13List.[*].isbn13":{"$eq":"9780061031328"}}

   This is Stargate Document API specific syntax.

   Note that the value of the where key is JSON.

   The key of the JSON object is a JSON path.

   The value of the JSON object is an instruction to use an equals method with the value of 9780061031328 against the data at the end of the JSON path.

   This should return to us any document that has the object {"isbn13":"9780061031328"} in its isbn13List array.

2. Click Send:

   Notice that the document for the book “Thief Of Time” is returned

   

3. Select Get by isbn10 from the collection and click Send:

   Notice that once again, the document for the book “Thief Of Time” is returned

   

4. Select Get by Author from the collection and hit Send:

   Notice that you get both documents returned since Terry Pratchett is included as an author on both book info documents.

5. Now, go play. Change the queries, add more book info documents.

   As a start, replace “Terry Pratchett” with “Joanne Harris” in the Get by Author call and hit Send again.

   This time you should just see the data for “Wyrd Sisters” returned.

When you are done, select Delete book_catalog Collection from the collection and hit Send. This will delete the data from Cassandra.

That’s it!

Next time we’ll turn this into a Quarkus app that will retrieve data from the Open Library API, and store it in our Cassandra cluster using the Stargate Document API.

Check out Open Library here: https://openlibrary.org

Cheers!