Stargate brings Apache Cassandra to the Postman API Network
Author: Pieter Humphrey
Stargate v2 is now available on the Postman API Network, the most popular way to create, share, test, and document Web APIs. Postman users can quickly develop, test, and learn Apache Cassandra with a range of available performance and productivity tradeoffs. From high-performance, cloud-friendly Web APIs like gRPC and GraphQL to productive APIs like REST, and a schemaless JSON Document API, Stargate has your use case covered.
API-first development
As many Postman users are aware, API-first or API-only apps will be the default in just a few years, rendering traditional SaaS/custom apps “legacy.” That dynamic will bring API infrastructure into progressively sharper focus, and few are better positioned to add value for API developers than Postman.
Behind the firewall, private service-oriented architecture uses service registry and discovery tools like Netflix Eureka, Hashicorp consul, and other key-value stores like etcd. Public service-oriented architecture on the cloud needs similar directory capabilities that are independent of cloud providers. The Postman API Network is an easy-to-use directory that gives anyone on the internet — in any programming language — a simpler way to share, discover and consume APIs. It’s directly integrated into the hugely popular Postman application and is designed for humans as well as, of course, programmatic interfaces.
NoSQL with Stargate and Apache Cassandra
Stargate is a data API gateway that elevates gRPC to native-driver-level performance while modernizing Apache Cassandra for other web APIs and JSON. Stargate completes the transformation of the Apache Cassandra powerhouse database to a cloud service that simplifies data access and management.
What does Stargate do for developers?
- Automatically provides app-to-database web APIs over secure gRPC, GraphQL, and REST endpoints.
- Go multi-model with Stargate and transform Cassandra into a document database using the JSON Document API. Start schema-less, or use JSON Schema for structured or semi-structured JSON.
- Upgrade Cassandra auth with table-based and JWT-based token authorization for both driver and API connections.
What does Stargate do for operations?
- Stargate v2 transforms Cassandra into modular architecture by separating coordinator and storage nodes into independently deployable and scalable services. Tune performance to best match your query or storage-intensive workload.
- Stargate v2 architecture is further modularized by separating web API services and gRPC/Native driver nodes into independently deployable and scalable services. Tune performance to best match your API workload.
- Stargate deploys anywhere — bare metal, VMs, Docker, GKE, EKS, K8ssandra, DSE — and is available as a managed service on DataStax Astra DB.
Stargate on Postman API Network
With Stargate, Postman users can work with the popular Apache Cassandra database directly over HTTP and HTTP/2, with a range of Web API options to choose from in trading off performance for developer productivity.
- gRPC API (fastest)
- GraphQL API (faster)
- REST API (easy)
- JSON Document API (easiest)
You can learn more about these options on the Postman Blog. What’s interesting here is that with the release of Stargate v2, gRPC performance is equivalent to native database driver wire speed. As many Cassandra use cases center around scale and performance, a low-latency Web API was critical to complete the Stargate portfolio. Stargate ensures that cloud native, real-time system development over HTTP is an option.
Join the livestream on November 3, 2022 (or check out the replay) to learn more about this driverless (r)evolution in high-performance systems with gRPC, hosted by Postman’s Ian Douglas and DataStax’s Jeff Carpenter!
Finding Apache Cassandra and Stargate on the API Network
Searching for Cassandra, DataStax, or Stargate on the Postman API Network will get you right there.
The DataStax Team Page
Welcome! Let’s suit up and get started making something awesome. If you’d like to see an API and data serialization format that Stargate doesn’t yet support, Stargate is APL 2.0 licensed and extensible. Check out the experimental work on a Dynamo DB API from the community!
Don’t know which API is right for your use case? Not to worry, head over to the Postman Blog for guidance on choosing the right data API for Apache Cassandra.
Stargate-Cassandra Workspace
It’s important to realize that Stargate runs alongside a Cassandra cluster, in between your application and Cassandra database. The workspace contains collections, environments, and more to help you get started.
- 3 Generally Available collections (Document-API-myworld, GraphQL API-library, REST-API:users_keyspace)
- 1 Beta API for gRPC (Stargate-gRPC-API:BETA)
- 1 work-in-progress collection (Document-API:library)
- Environments for executing collections against both Stargate running locally and as a service on DataStax Astra DB
Running Stargate Postman Collections with DataStax Astra DB
DataStax recommends using Astra DB since Stargate is already set up, and runs as a managed service. Postman environments are provided for you in order to run on Astra DB in the team space. This article will walk you through it step by step, or if you prefer, you can watch awesome community member Khushi Sharma demonstrate this on YouTube:
It’s easy to create a Serverless Cassandra database on Astra DB. Don’t worry, no credit card is required, and running these examples is well within what’s provided by the Astra DB Free Plan. Zero low-level infrastructure knowledge is required so there is no need to specify AWS, Google Cloud, or Azure virtual machine types. You’ll have a running database in just a few minutes, and loading a CSV of your own data to play around is fairly straightforward.
When you are prompted in the Astra DB console to save and download your token details, make sure to store them in a safe place as it is the only time you will get this information, and you’ll need it later for authentication for Postman Web API calls to Stargate/Cassandra.
Great, let’s create your Astra DB Database and API Tokens.
Access control for the new keyspaces
In your Astra DB Console > Organization Settings > Role Management, look for the Role that matches your database name and click ‘edit’. In this case, the database was named ‘postman1’.
Then click the “select all” link and scroll down to the bottom and tick ‘apply permissions to all databases in this organization’ which will select 45 permissions. Click Edit Role to save and exit. Note this is strictly for development / instructional purposes and should never be used in production.
Once you are done with that, create the myworld, library, and ks1 keyspaces in the Astra DB console, by clicking the “Add Keyspace” button:
Postman Environments for Stargate
Next, return to Postman and the stargate-cassandra workspace. You’ll notice several environments in the environments tab on the left. You’ll want to use the ‘Stargate Astra API Environment’ to run any of these collections or APIs:
- REST API-users-keyspace
- Document-API-myworld
- GraphQL API-library
- gRPC-API:BETA
Make sure to fork both the ‘Stargate Astra API Environment’ and each of the collections above to your own personal workspace before editing. If the workspace you’re forking into is not private (e.g. another team or public workspace), maintain your Database access token under CURRENT VALUE (not INITIAL VALUE) so you don’t expose the value to others in a team or public workspace.
Once forked, update the “CHANGE_ME” settings in the environment for
- ASTRA_DB_ID
You can get this from the Astra DB console > Dashboard, labeled Database ID. Note this is not the datacenter ID from the database detail page, this is only available on the Dashboard where all databases are listed. - ASTRA_DB_REGION
In the Astra DB console > database overview tab, labeled Region. (e.g. us-west1) - AUTH_TOKEN
This is the downloaded/copied token from the database creation procedure above (begins with ‘AstraCS:’ )
Don’t forget to click save!
Running Stargate Postman Collections
Now you can use Postman to execute sample API calls against your Astra database. Go back to the Collections area in Postman and select one of the collections mentioned above. Make sure you are in your personal workspace, and then, in the environment picker in the upper right on the Postman Collections Runner select the ‘Stargate Astra API Environment’ (the one you forked), and then press the Run button to execute the collection. When prompted for which tests you’d like to run, deselect tests with the label (Stargate OSS Only) after them (located at the beginning and end of the test list) or those will error since you aren’t running stargate locally.
Each collection executes a series of commands demonstrating how to use that API to insert, retrieve, and delete data.
The Beta gRPC API
Since this is in beta, a few extra steps are needed. Once you fork the API to your Personal Workspace, it’s possible the Protobuf definitions will get lost. When examining a specific test, look for the telltale ‘Select a method’. Choose Import a .proto file, first importing stargate.proto and then query.proto if necessary. Don’t change the filenames or dislocate them in different directories, as there are import statements that cross-reference the two files. If supplying URLs don’t work, just download the files locally and upload. This would prompt you to create an API, which we’ve typically named stargate-gRPC and versioned ‘1.0'. Make sure to click the lock icon as TLS encryption does need to be enabled.
Since it isn’t a collection, you run tests individually. At times, the Postman Collection Runner may need to be reminded of which service definition from the gRPC protobuf a given test call is using. You can associate them and accept the default association as shown below.
‘Insert batch data’ is the only method that uses the ExecuteBatch service definition, the rest use ‘ExecuteQuery’.
Running Stargate Postman Collections with Stargate OSS
You can run Stargate and Cassandra yourself, of course. Let’s give you an idea of the work involved.
Install Docker Desktop and Pull Docker Images
Make sure you have Docker desktop installed and configured with at least 4GB of memory. Below we’ll show you how to start all the containers you need using docker-compose. While docker-compose is capable of pulling the required images on your behalf, you can also pull them manually to make docker-compose start more quickly:
% docker pull stargateio/coordinator-4_0:v2
% docker pull stargateio/restapi:v2
% docker pull stargateio/docsapi:v2
% docker pull stargateio/graphqlapi:v2
These images come from the Stargate repositories on DockerHub. They include an image for the coordinator, plus an image for each API that you might wish to run: restapi, graphql, and docsapi. The coordinator image contains an Apache Cassandra 4.0 backend, and an endpoint for the high-performance gRPC API.
Clone Stargate Repo
Next let’s clone the Stargate GitHub repository and locate the docker-compose files.
% git clone https://github.com/stargate/stargate.git
% cd stargate
% git checkout v2.0.0
% cd docker-compose/cassandra_4–0
This puts you in a directory with files that enable you to run Stargate in two different ways: a regular mode with a backing Cassandra cluster, and a development mode that runs an embedded Cassandra node inside the Stargate coordinator.
Run in Stargate in Development Mode
Let’s use a script that starts Stargate in development mode since it starts up more quickly. The script just sets up a few environment variables and delegates the rest of its work to docker-compose. Note that these settings are not recommended for production use, so make sure you’re just doing local development.
% ./start_cass_4_0_dev_mode.sh -t v2
Then you can watch in Docker Desktop as all of the containers are started:
Environments for Self-managed Stargate
Going back to Postman, select the Environments option again, choosing the “Stargate OSS API Environment”. You won’t need to fork the environment for initial testing, as the default auth_username and auth_password of cassandra/cassandra are fine for trying things out. You will want to fork the environment into a personal workspace when you change these values for use with production deployments. When in the Postman Collections Runner, you won’t need to exclude the tests marked ‘Stargate OSS Only’ as you are now running it locally, you should be able to run all tests. You’re ready to execute the API collections against your Stargate OSS deployment.
Have fun out there in the API space, and reach out if you need help building something awesome!