Stargate REST API QuickStart

Time to complete: 5 minutes

Stargate is a data gateway deployed between client applications and a database. In this QuickStart, you’ll be up and running on your local machine with the REST API plugin that exposes CRUD access to data stored in Cassandra tables.

Prerequisites

To use Stargate you need:

  • Docker installed and running

  • cURL to run REST queries

Pull the Docker image

This image contains the Cassandra Query Language (CQL), REST and GraphQL APIs, and GraphQL Playground along with an Apache Cassandra 3.11 backend.

docker pull stargateio/stargate-3_11:v0.0.8

Start the Stargate container

Start the Stargate container in developer mode. Developer mode removes the need to set up a separate Cassandra instance and is meant for development and testing only.

docker run --name stargate \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -p 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=3.11 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-3_11:v0.0.8

The ports align to the following services and interfaces:

Table 1. Default Port assignments for Stargate
Port Service/Interface

Port 8080

GraphQL interface for CRUD

Port 8081

REST authorization service for generating tokens

Port 8082

REST interface for CRUD

Port 9042

CQL service

Using the Auth API to generate an auth token

In order to use the Stargate Document API, an authorization token must be generated to access the interface.

The step below uses cURL to access the REST interface to generate the needed token.

Generate an auth token

First generate an auth token that is required in each subsequent request in the X-Cassandra-Token header. Note the port for the auth service is 8081.

curl -L -X POST 'http://localhost:8081/v1/auth' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "username": "cassandra",
    "password": "cassandra"
}'

You should receive a token in the response.

{"authToken":"{auth-token}"}

Use the auth token

Store the auth token in an environment variable to make it easy to use with cURL.

export AUTH_TOKEN={auth-token}

Using Postman

If you prefer, you can use Postman as a client interface for exploring REST APIs (download here). We’ve provided a Stargate REST API Postman Collection that you can import in Postman to play with the examples shown in this walkthrough.

Now you’re ready to use the REST API for CRUD operations.

Creating schema

In order to use the REST API, you must create schema that defines the keyspace and tables that will store the data. A keyspace is a container for which a replication factor defines the number of data replicas the database will store. Tables consist of columns that have a defined data type. Multiple tables are contained in a keyspace, but a table cannot be contained in multiple keyspaces.

Creating a keyspace

Before you can start using the REST API, you must first create a Cassandra keyspace and at least one table in your database. If you are connecting to a Cassandra database with existing schema, you can skip this step.

Note that you must create an auth token first.

Send a POST request to /v2/schemas/keyspaces. In this example we use users_keyspace for the name, and 1 for the number of data replicas.

curl --location --request POST 'localhost:8082/v2/schemas/keyspaces' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "name": "users_keyspace",
    "replicas": 1
}'

Creating a table

Send a POST request to /v2/schemas/keyspaces/{keyspace_name}/tables to create a table. Set the table name and column definitions in the JSON body.

curl --location \
--request POST 'localhost:8082/v2/schemas/keyspaces/users_keyspace/tables' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
	"name": "users",
	"columnDefinitions":
	  [
        {
	      "name": "firstname",
	      "typeDefinition": "text"
	    },
        {
	      "name": "lastname",
	      "typeDefinition": "text"
	    },
	    {
	      "name": "email",
	      "typeDefinition": "text"
	    },
        {
	      "name": "favorite color",
	      "typeDefinition": "text"
	    }
	  ],
	"primaryKey":
	  {
	    "partitionKey": ["firstname"],
	    "clusteringKey": ["lastname"]
	  },
	"tableOptions":
	  {
	    "defaultTimeToLive": 0,
	    "clusteringExpression":
	      [{ "column": "lastname", "order": "ASC" }]
	  }
}'

Information about partition keys and clustering keys are found in the CQL reference.

Checking keyspace, table, and column existence

To check if a keyspace, tables, or particular table columns exist, execute a REST query with cURL:

For keyspaces:

curl -L -X GET 'localhost:8082/v2/schemas/keyspaces' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'X-Cassandra-Token: $AUTH_TOKEN'

returns

// LLP: GET THE RETURN RESULT
["data_endpoint_auth","users_keyspace","stargate_system","system","system_auth","system_distributed","system_schema","system_traces"]

To get a particular keyspace:

curl -L -X GET 'localhost:8082/v2/schemas/keyspaces/users_keyspace' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'X-Cassandra-Token: $AUTH_TOKEN'

returns

// LLP: GET THE RETURN RESULT

For tables:

curl -L \
-X GET 'localhost:8082/v2/schemas/keyspaces/'users_keyspace'/tables' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'X-Cassandra-Token: $AUTH_TOKEN'

returns

// LLP: GET THE RETURN RESULT
["users"]

To get a particular table:

curl -L \
-X GET 'localhost:8082/v2/schemas/keyspaces/'users_keyspace'/tables/users' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'X-Cassandra-Token: $AUTH_TOKEN'

returns

// LLP: GET THE RETURN RESULT

For columns:

curl -L \
-X GET 'localhost:8082/v2/schemas/keyspaces/'users_keyspace'/tables/users/columns' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'X-Cassandra-Token: $AUTH_TOKEN'

returns

// LLP: GET THE RETURN RESULT
["users"]

To get a particular column:

curl -L \
-X GET 'localhost:8082/v2/schemas/keyspaces/'users_keyspace'/tables/users/columns/email' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'X-Cassandra-Token: $AUTH_TOKEN'

returns

// LLP: GET THE RETURN RESULT
["users"]

Interacting with data stored in tables

Write data

First, let’s add some data to the users table that you created. Send a POST request to /v2/keyspaces/{keyspace_name}/{table_name} to add data to the table. The column name/value pairs are passed in the JSON body.

curl --location --request POST 'localhost:8082/v2/keyspaces/users_keyspace/users' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "firstname": "Mookie",
    "lastname": "Betts",
    "email": "mookie.betts@gmail.com",
    "favorite color": "blue"
}'
curl --location --request POST 'localhost:8082/v2/keyspaces/users_keyspace/users' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "firstname": "Janesha",
    "lastname": "Doesha",
    "email": "janesha.doesha@gmail.com",
    "favorite color": "grey"
}'

Read data

Let’s check that the data was inserted. Send a GET request to /v2/keyspaces/{keyspace_name}/{table_name} to retrieve all the data:

curl GET \
--location 'http://localhost:8082/v2/keyspaces/users_keyspace/users' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \

Now let’s search for a particular record using a WHERE clause. The primary key of the table can be used in the WHERE clause, but non-primary key columns cannot be used. Send a GET request to /v2/keyspaces/{keyspace_name}/{table_name} to retrieve the row for Mookie:

curl GET \
--location 'http://localhost:8082/v2/keyspaces/users_keyspace/users' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-urlencode 'where={"firstname": {"$eq": "Mookie"}}'

Update data

Data changes, so often it is necessary to update an entire row. To update a row, send a PUT request to /v2/keyspaces/{keyspace_name}/{table_name}/{path}. The {path} is comprised of the primary key values. In this example, the partition key is firstname "Mookie" and the clustering key is lastname "Betts"; thus, we use /Mookie/Betts as the {path} in our request.

curl --location \
--request PUT 'localhost:8082/v2/keyspaces/users_keyspace/users/Mookie/Betts' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "email": "mookie.betts.new-email@email.com"
}'
Updates are upserts. If the row doesn’t exist, it will be created. If it does exist, it will be updated with the new row data.

Delete data

To delete a row, send a DELETE request to /v2/keyspaces/{keyspace_name}/{table_name}/{path}. In this request we delete all data with the primary key firstname of Mookie:

curl --location \
--request DELETE 'localhost:8082/v2/keyspaces/users_keyspace/users/Mookie' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'

Voila! For more information on the REST API, see the see the Using the REST API or the REST API in the Data API section.