Toggle Menu

Access Cassandra Via Stargate APIs

If you are building cloud-native apps, you are using microservices that give you REST or GraphQL APIs. Stargate gives you these APIs with zero work on your part. Stargate provides several interfaces, and we’ll focus on four of them:

  • Authentication
  • REST
  • GraphQL
  • GraphQL Playground

In this module, we will look at using Stargate with Cassandra Operator. But, [Spoiler Alert] Stargate is already integrated into K8ssandra.

Get Started
How Does Stargate Fit into the Kubernetes Architecture?

How Does Stargate Fit into the Kubernetes Architecture?

Stargate runs as a Docker image within a pod that we install using a deployment. As is customary in Kubernetes, we place a service in front of the deployment. The service listens on three ports (8080, 8081 and 8082) for requests for the Stargate interfaces (GraphQL, Auth and REST respectively).

In this module’s example configuration, we have an ingress installed on port 80. The ingress inspects the URL paths and routes the requests to the appropriate service port.

The service forwards requests to the corresponding port of the pod. One of the benefits of using the service is that if the pod dies and must be restarted, the interface for the ingress does not change.

The deployment monitors the pod to keep the pod running. Another possible benefit of the deployment is that, if we need to scale up Stargate, we can do so merely by increasing the number of replicas in the deployment.

Next: How Does Auth Work?

How Does Auth Work?

The Stargate auth interface allows you to supply the Cassandra credentials, one time, in exchange for an auth token. When the Cassandra Operator creates a Cassandra cluster, the operator stores the Cassandra credentials in a Kubernetes secret. To get the auth token from the Stargate auth interface, a client can retrieve the credentials from the secret and supply them as part of the request. In response to this request, the auth interface provides an auth token. Clients can then use the auth token to access the other Stargate APIs such as REST or GraphQL.

In this module’s configuration, the ingress determines an auth request by identifying the URL path starting with /v1/auth. When the ingress sees this path, the ingress forwards the request to port 8081 on the Stargate service. The service uses the same path to access port 8081 on the Stargate pod. The pod, in turn, verifies the credentials with the Cassandra cluster and then creates the auth token, which is ultimately returned to the client.

Next: How Does the REST API Work?
How Does Auth Work?
How Does the REST API Work?

How Does the REST API Work?

The REST API provides REST access to a Cassandra table using information embedded in the REST URL endpoint. The REST endpoint path must start with /v2/keyspaces. This base path causes the ingress to forward the request to the Stargate service on port 8082. The remainder of the URL encodes the keyspace name, the table name, and the search criteria (such as the primary key value).

The Stargate service forwards this entire URL to the pod. The pod then decodes the URL and formualtes a Cassandra query, and returns the results back to the client.

Note that the client embeds the auth token in the HTTP headers of the request.

Next: How Does the GraphQL API Work?

How Does the GraphQL API Work?

Like the REST API, the GraphQL API provides GraphQL access to a Cassandra table. The big difference between REST and GraphQL is that, with REST, the client receives all the table columns back. But, with GraphQL, the client can specify how much data the API will return. This can optimize API traffic.

Similar to how the REST API works, the ingress inspects the request URL for a base path of /graphql. Upon identifying this path, the ingress forwards the request to port 8080 on the Stargate service. In turn, the service forwards the request to the pod on port 8080.

Unlike REST requests, GraphQL requests embed only the keyspace name in the URL. The remainder of the request uses a JSON format within the body of the request. As previously mentioned, this request body not only specifies the table name and search criteria, but also includes a specification of the desired output.

The pod parses this information and formulates a query to the Cassandra table. The pod then returns the results of the query to the client.

Similar to the REST API requests, GraphQL clients embed the auth token in the HTTP headers of the request.

Next: What is the GraphQL Playground?
How Does the GraphQL API Work?
What is the GraphQL Playground?

Example Playground UI

The GraphQL Playground UI is an interactive GraphQL client that you can run in a browser. The Playground understands GraphQL and helps users formulate queries by supplying command hints. Using the Playground, users can formulate GraphQL queries, submit the queries to the GraphQL API, and view the results.

Users configure the Playground to talk to the Stargate GraphQL API by supplying the Playground with the GraphQL URL and the auth token.

The web-server for the Playground has a URL base path of /playground. So, when the ingress fields HTTP requests with this base path, the ingress forwards these requests to the Stargate service on port 8080. The service forwards the request on to the pod, also using port 8080. The pod contains a web-server that services the Playground app.

Next: Skill Building

Skill Building

Do you want to try out Stargate's REST or GraphQL APIs to Cassandra? Learn how to use these APIs and see Stargate in action.

Access Cassandra Via Stargate APIs

Use REST and GraphQL to access your Cassandra database


For cloud native apps, you want API access to Cassandra. Stargate gives you secure REST and GraphQL APIs.

This scenario picks up where the scenario named Managing Cassandra Clusters in Kubernetes Using the Cass-Operator leaves off. If you have not yet worked through that scenario, you may want to check it out here.

In this scenario, we'll:

  • Set up a Cassandra cluster running on Kubernetes and install the example Pet Clinic app
  • Install Stargate and get an auth token for accessing the APIs
  • Use Stargate's REST API to access Cassandra
  • Use Stargate's GraphQL Playground to explore the GraphQL interface
  • Use cURL to access Stargate's GraphQL interface

Note: As shown in previous scenarios, the Pet Clinic example app provides its own backend microservice. To keep this scenario relatively brief, we won't modify Pet Clinic app to replace the backend with the Stargate APIs. But, given more time, we could!
However, we will use the Pet Clinic table named petclinic_reference_lists. One row of this table holds the list of pet types as a Cassandra set. The primary key value for this  row is pet_type. We'll use this table so you get the intuition that the Stargate APIs could provide a viable microservice for the app.


You're going to love Stargate and its APIs!

Time to Complete

20 minutes




Do you have a suggestion or issue you’ve discovered?

Share Feedback

More Resources

Items related to Kubernetes

Stargate Website

Stargate Website

Stargate - the data API for Astra and DSE

Learn More
Stargate: Open Source APIs for Cassandra

Stargate: Open Source APIs for Cassandra

Developer Newsletter - Stargate APIs for Cassandra

Read More
Stargate 1.0 in Astra; REST, GraphQL, & Schemaless JSON for Cassandra Dev

Stargate 1.0 in Astra; REST, GraphQL, & Schemaless JSON for Cassandra Dev

Stargate 1.0 in Astra

Read More