This is the second post in a series on how to use Stargate APIs. With our coding scenario and 15 minutes, you can learn how to use the Stargate GraphQL API right in your browser to solve some of the issues you might have experienced with REST API.

If you’ve been working with APIs for a while or went through our first post in this series on how to get started with the Stargate REST API — you’ll be aware of the downsides to any REST API:

Over fetching: The API will return more data than you need
Ambiguity: There is no type of safety of the data you get with a REST API.
Wasted bandwidth: The over fetching will cost bandwidth with multiple network requests

Like the Stargate REST API, the Stargate GraphQL API is designed for Apache Cassandra® databases. However, it offers a significant advantage over REST APIs by allowing you to manipulate multiple data items with a single query and customize your queries to retrieve exactly the data you want. This ability eliminates over-fetching along with the extra work and wasted bandwidth resulting from it.

While you can add Stargate GraphQL API to an existing Cassandra deployment, you don’t need a pre-existing database to start learning how to use it. If you don’t already have one, you can create a new Astra DB for free here. Astra DB is a serverless database based on Cassandra and it comes with GraphQL API already enabled.

In just a few minutes, you can be up and running with our Katacoda scenario, which will show you how to use Stargate GraphQL API to run standard create, read, update, and delete (CRUD) operations on the data in your Cassandra database. While you don’t need to know Cassandra Query Language (CQL) for this tutorial, having some familiarity with it will help you to better understand some of Cassandra’s idiosyncrasies, such as partition keys and clustering keys. If you’d like to dive deeper into Cassandra and CQL, DataStax has you covered with a free learning series on Cassandra Fundamentals.

The technologies we’ll use in the scenario are:

You’ll also jump into the documentation for the Stargate Documents API but only briefly in order to copy the necessary export commands you will need when you’re setting up the environment for the scenario. You’ll just be copying those over into your terminal. These copied environment variables will be identical between the Documents API and GraphQL API so there is no harm from either tab.

Exploring your options for using the Stargate GraphQL API

GraphQL is an open-source query language and runtime used to fetch data from a supported API into your application. Stargate GraphQL API was designed specifically for Cassandra and comes already enabled in Astra DB. Stargate GraphQL works by scanning your database and automatically creating HTTP endpoints to serve queries and mutations for the objects it finds in the database.

With the Stargate GraphQL API, you can get the data you need into your apps directly from Cassandra with a CQL-first approach. A CQL-first approach directly translates CQL tables into GraphQL types, mutations, and queries and automatically generates the GraphQL schema from the keyspace, tables, and columns defined. You’ll get a standard set of mutations and queries for searching and modifying your table data but you won’t be able to do any customization of those.

If you want to use a more native GraphQL approach to access your data, you can use a Schema-first approach instead. This approach to using Stargate GraphQL reduces the need to know CQL because the creation and modification of the CQL tables in the Astra DB (table and column names for example) to match the GraphQL types are abstracted, and the resulting tables use GraphQL-centric names for types that correspond. Although you don’t have to give up all the control if you don’t want to since the GraphQL schema can be decorated with CQL annotations.

If you’ve used GraphQL before, you’ll find the schema-first approach familiar in how you create GraphQL types, mutations, and queries. One big advantage of this approach is that it allows you to deploy and update your schema without having to recreate the tables and columns directly.

Perhaps most importantly, a schema-first approach will allow you to customize your queries to eliminate over-fetching, which saves on bandwidth and improves the performance of your app.

Using the Stargate GraphQL API with a schema-first approach

Our scenario uses cURL commands, so we’ll be using the terminal as opposed to the GraphQL Playground. However, the GraphQL Playground is worth mentioning here because it offers another easy way to work with GraphQL. The server paths are structured to allow you to easily create new schemas and interact with the GraphQL APIs using built-in queries.

Getting back to our scenario, once we get our environment ready to go in GraphQL, we’ll use a series of cURL commands to try out all the basic CRUD operations:

Create a table and add some records to it
Request a record from the table
Update a record
Delete a record

And to make the JSON output easier to read, we’ll include in our cURL commands some code to pipe the output into jq (a “pretty printer” for JSON).

With our Katacoda scenario, you can learn the basics of using Stargate GraphQL API with Astra DB in your browser in just 15 minutes. Then you can start applying the same steps to work with your own Cassandra database or Astra DB. If you don’t have a database to work with yet, jump over to the Astra DB site to register for a free account and start learning today!

Follow the DataStax Tech Blog for more developer stories. Check out our YouTube channel for tutorials and here for DataStax Developers on Twitter for the latest news about our developer community.

How to get just the data you need with the Stargate GraphQL API in a simple coding scenario

Exploring your options for using the Stargate GraphQL API

Using the Stargate GraphQL API with a schema-first approach

References: