DEV Community: Doug Wettlaufer

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

Doug Wettlaufer — Tue, 04 Oct 2022 18:01:12 +0000

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.

References:

Qualify Your Database Needs with DataStax Astra Stargate REST API

Doug Wettlaufer — Thu, 29 Sep 2022 15:20:57 +0000

This is the first post in a series we introduced here on using Stargate application programming interfaces (APIs) to quickly qualify your database needs right in your browser. We’ll begin with the most common API — the representational state transfer (REST) API. To help you learn how to use it, we’ve created a Katacoda scenario that will show you how to perform standard create, read, update and delete (CRUD) operations in your Apache Cassandra® database.

When you want to build a world-class app, you need to think about scalability, availability, and performance. So you’re probably looking for a cloud-native solution. And a run-of-the-mill database won’t cut it for your backend.

For many of your scalable application needs, Cassandra is a one-stop solution. It can give you the fastest lookup speed. And since it can be globally distributed, it’s highly available for your clients no matter where they are located.

Cassandra requires a fair amount of expertise and effort to run. So the Cassandra experts at DataStax created Cassandra-as-a-service called Astra DB. Standard API access lets you get up and running with Cassandra in minutes and enjoy all the benefits with none of the hassle. Now, you can try it out in the scenario we’ve created to help you get started using this API right in your favorite browser.

In this scenario, you’ll learn the basics of how to use the Stargate REST API built on Cassandra. Specifically, we’ll show you how to use the REST API to create tables in your Cassandra database and perform CRUD operations on them using client URL (cURL).

The technologies we’ll use in this scenario are:

Astra DB: Serverless cloud database-as-a-service based on Cassandra.
Stargate REST API: Most common API for handling app data.
Apache Cassandra®: Open-source database management system.

Creating a Cassandra Database with Astra DB

Cassandra is what we’ll be basing your database on, so you get the best options of high performance, scalability, throughput, and availability. Cassandra is a free and open-source database management system. It has been used by hundreds of companies to support data-driven, mission-critical applications that frequently require a global scale. For example, Cassandra is used by Apple, eBay, Hulu, Instagram, Netflix, Spotify, and Uber, just to name a few.

Unfortunately, Cassandra, being a distributed database that runs on large clusters, can be complicated to operate. That’s no issue in the big corporations with experienced engineers with time to focus solely on their databases. But it might be an issue for you. We know a lot of developers want to use Cassandra without having to start from scratch on their own.

That’s why we built Astra DB. It’s a cloud database-as-a-service (DBaaS) built on Cassandra. We designed it to make it easy and fast to start building apps that can scale fast. You can get started for free and pay as you go, once you are ready to go into production.

Using the Stargate REST API

To make it easy for your app to interact with the database, we created Stargate.io. It’s an open-source data gateway with three APIs that work with Astra DB right out of the box. Instead of having to read up on different APIs and databases, all you have to do is pick one of the three Stargate APIs and get to work on your application.

You can read more about the GraphQL API and Document API in the intro post to this series and the following posts that will take a closer look at each of them. For now, we’ll focus on the REST API, which is the most commonly used.

The REST API concept has been around for over 20 years now. It’s still popular because it’s so easy to use. It lets you use standard HTTP commands like POST, PUT, GET, and DELETE to exchange data in JavaScript Object Notation (JSON) or other formats that are well-known to most developers.

With the Stargate REST API, you can implement your application and Cassandra database separately. You can then use the API to call on microservices between the two. The clean cuts between all your moving parts make it easier for you to scale whatever it is you’re building. You can even use our REST API to create new tables in your database.

Try out the Stargate REST API in your browser

We’ve set up a scenario for you to try out the Stargate REST API for free. You can use the REST API Katacoda scenario to set up a world-class, cloud-native database and perform CRUD operations on your data in just a matter of minutes — all within your browser of choice.

Learn more about Astra by also going through our other scenarios on our developer portal.

All you need to do is sign up for an Astra account to start writing and reading data. DataStax gives you a free credit of USD 25 every month so you can check it out without entering any credit card details. If you experience any friction in the sign-up process, have a look at this short guide.

Sign up for an Astra DB account today and get started with the Stargate REST API in a matter of minutes.

References

Stargate and Cassandra 4.0 - Better Together

Doug Wettlaufer — Thu, 11 Aug 2022 20:09:51 +0000

Six years in the making, Apache Cassandra has reached its 4.0 GA release. This is a big milestone for one of the most important open source projects, and a significant step forward in the world of NoSQL and Fast Data.

Highlights in 4.0

This new release brings a lot of exciting features to Apache Cassandra. A few highlights include:

Java 11 support;
Virtual tables;
Improved streaming.

For the full list head over to the official Apache Cassandra docs. After reading over everything Cassandra 4.0 brings to the table you might be wondering, “What more could I need?”. Well, that’s where Stargate comes in.

What Is Stargate?

Stargate is a data gateway providing a multi-model set of APIs through which to interact with your Cassandra database. DataStax runs Stargate as part of Astra DB, and Stargate can also be deployed on prem with DataStax Enterprise. And of course Stargate is an open source project in its own right that works with open source Apache Cassandra.

So why does Stargate matter to developers, and to the Cassandra community?

Focus On What You Care About

For many developers a database is simply a means to an end. We spend our days trying to rapidly deliver incredible applications to benefit our users. Applications typically require some form of data persistence. This may mean direct database access with a driver of some sort but others would rather have an API that allows them to think about and interact with their data in a more familiar vernacular. At this point we’re typically left to either spin up yet another data service or add a new endpoint to our already growing data proxy. But now there’s another option, Stargate.

When we say Stargate is multi-model, this is the problem we’re solving. Whatever a developer’s preferred API for data interactions, Stargate offers a single gateway to support that API. Rather than incurring the cost of supporting an ancillary service in order to expose, say, a new GraphQL API to interact with your data you can instead install Stargate as part of your Cassandra cluster leaving more time to focus on what you really care about, your users.

Any Way You Want It

As discussed in our previous blog, Stargate is an “open source data gateway” that provides multiple APIs for interacting with your data in a familiar and secure manner. You could grab the Cassandra driver for the language of your choice and start developing from there (an option completely supported by Stargate), and now you can also choose one of the APIs supported by Stargate that you’re already familiar with such as:

REST
Documents API
GraphQL
gRPC

The REST API in Stargate enables you to work with your data in a RESTful format. It exposes a complete CRUD interface for your entire data lifecycle, from schema creation to data manipulation and retrieval. Additionally, there is the Documents API that allows for data management in a schemaless manner which allows for fast iteration without worrying about data modeling. See this blog article for a deeper dive into the Documents API. Aside from the more traditional, RESTful interfaces there is also the GraphQL API. This API allows you to interact with your data in either a cql-first or schema-first manner. This new schema-first version is a reimagining of the original cql-first API and provides a more GraphQL native interface that should be familiar to any GraphQL developer. Finally, there is the gRPC API currently in alpha. This new API brings with it all of the existing gRPC and HTTP/2 benefits while still accepting the CQL you’re used to.

Getting Started

Now that we’ve highlighted how Stargate can make Cassandra 4.0 even easier to work with, it’s time to give it a spin. Starting with v1.0.31 Stargate Docker images will support Cassandra 4.0 GA versions and beyond. Check out our docs and examples for simple getting started instructions.

What 4.0 Means for Stargate

Since pre-v1.0 Stargate we’ve supported Apache Cassandra 4.0. We’ve been there for alphas, betas, and release candidates but today we’re happy to announce that Stargate supports the official Apache Cassandra 4.0 GA release.

This is an evolutionary change for Stargate more than a ground-breaking step. To bring the flexibility and ease of use that Stargate offers to as many developers as possible, we have always targeted multiple platforms (open source Apache Cassandra, Astra DB, and DataStax Enterprise) as well as multiple versions of Apache Cassandra (3.x and now 4.x). So you don’t need to worry about breaking changes or backwards compatibility. Stargate will continue to support these platforms and versions going forward.

Features like improved internode messaging will benefit Stargate, but we don’t have to do anything in Stargate to receive those benefits; they’ll happen organically below the Stargate coordinator layer. Features like improved streaming offer new opportunities for streaming support in Stargate which we hope to take advantage of in the future. For now rest assured that new streaming features in Stargate will be planned to work with both 4.x and 3.x.

The world’s most scalable open source database just got better. As a result, Stargate got better too.

Get a Head Start on Your App Development with Flexible DataStax Stargate APIs

Doug Wettlaufer — Thu, 09 Jun 2022 20:35:56 +0000

This is the introductory blog to explain our upcoming series about the Stargate Data APIs. Each post will take you on a deeper dive into how each application's programming interface (API) works and what you’ll want to use it for.

If you want to build an enterprise-level app that can handle as much data as Apple, Netflix, or Capital One, you’ll need to run it on Apache Cassandra® as they do.

But you no longer have to have a huge team of developers. We’ve created the project Stargate to help you. Stargate is an open-source data gateway that brings together your app and databases by helping to abstract Cassandra-specific concepts from app developers. It’s also an important part of DataStax Astra DB, our multi-region, multi-cloud, serverless database service built on Apache Cassandra.

With the three Stargate APIs, REST, Document, and GraphQL, you have all you need to manage your Cassandra database without having to build your own Cassandra-specific interface.

How you will benefit from the Stargate Data APIs

Figure 1: The most common DataStax API on Stargate — REST API — lets apps run seamlessly with Cassandra in addition to any relevant microservices.

It can be challenging to work out exactly how to retrieve and update data when you’re working on a new app. You may want to pull from several microservices like payments, analytics, and a user action log.

Instead of having to sort through drivers or even code your own interface between all of your moving parts and your database, you can continue to use APIs and technologies you’re already familiar with (like REST) via the Stargate APIs.

They will let you set up the interface between your app and its data in a Cassandra database with minimal work on your behalf. Even if your app is already up and running.

You’ll get all the benefits of scalability without the hazard of your interface breaking down when your app starts to attract a lot of users. Plus you won’t have to deal with the other common concerns like health checks, metrics, or authentication as these are all provided out of the box.

Be up and running in seconds with the Stargate REST API

REST APIs have become very popular because they effectively cover the needs for basic HTTP operations.

With the Stargate REST API, you get the most popular, well-known interface with a Cassandra database that’ll work no matter how big your app grows to be. You can use it to get a clean separation between your app and the server that holds your data.

Figure 2: DataStax Stargate REST API comes with all Astra databases. You can set one up for free at astra.datastax.com.

Since you’re probably already familiar with REST APIs, you can get up and running in seconds with the Stargate REST API. To start, simply set up a database for free in DataStax Astra DB.

You can use the Stargate REST API to cover a wide range of use cases. For example, managing a product catalog and keeping it up to date with the amounts of each product in stock. Or letting librarians search for and suggest new books based on the authors or genres each visitor likes.

You can do a lot of great work with the REST API. But one of the challenges is that you can’t control the amount of data that is returned from the database. So if you need a truly scalable app that draws on the relationships between data, you’ll want to know about the GraphQL API.

Only get the data you need with the Stargate GraphQL API

You might not be building one of the world’s largest social networks, but you can still enjoy the same technology that lets Facebook handle a large number of datasets.

Developers at Facebook created GraphQL to get just the pieces of data needed in every instance and make it easy to understand. That’s how we know the Stargate GraphQL API will also work for you.

Without this API, this task could end up as an insurmountable mess when your app starts to gain traction with users. But with the GraphQL API, you can simply set it up to retrieve exactly the data you need from the start. This saves you a lot of complexity and bandwidth.

Figure 3: DataStax Stargate GraphQL API comes with all Astra databases. You can set one up for free at astra.datastax.com.

The biggest disadvantage to GraphQL is that the possibilities can seem overwhelming. That’s why we created a thorough GraphQL API demo that helps you start using it with Stargate.

Be sure to read our second blog post in this series to learn more about what makes the GraphQL API so great to work with and just how to make it work for you.

Don’t worry about the schema — just use the Document API

Modern applications are built on APIs, and JSON documents are the most common way of expressing data payloads on those APIs. Stargate Document API makes it easy to serve a document-style API directly from any Cassandra database, allowing you to store and retrieve JSON documents without defining a database schema. This is a big deal because the traditional practice for Cassandra has been to define all your schema upfront.

Figure 4: DataStax Stargate Document API comes with all Astra databases. You can set one up for free at astra.datastax.com.

Document API serves up all your data as JSON documents and lets you interact with them in the most familiar HTTP methods. It also lets you represent the data just like you want it in your app. You can use this API to create, update, and retrieve documents and subdocuments.

You can get started using Document API now or read on in our third and final post in this series about the benefits and technology within our Document API.

For exclusive posts on all things data: Cassandra, streaming, Kubernetes, and more; follow DataStax on Medium.

References: