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

If you’re looking to just get started, you can try DataStax Astra DB and skip the installation steps.

The base URL will be https://DATABASE_ID-REGION.apps.astra.datastax.com/api/rest/v2. See the FAQ to learn where to find your DATABASE_ID and REGION.

Install cURL, a utility for running REST, Document, or GraphQL queries on the command line.
[Optional] If you prefer, you can use Postman as a client interface for exploring the APIs
- You will also find links to downloadable collections and environments in Using Postman
[Optional] If you going to use the GraphQL API, you will want to use the GraphQL Playground to deploy schema and execute mutations and queries.
[Optional] For the REST and Document APIs, you can use the Swagger UI.
Install Docker for Desktop
Pull a Stargate Docker image

Cassandra 4.0
Cassandra 3.x
DSE 6.8

For Stargate v2, you’ll need to pull an image for coordinator, plus an image for each API that you wish to run: restapi, graphql, and docsapi. The coordinator image contains a Apache Cassandra^™ backend, the Cassandra Query Language (CQL), and the gRPC API.

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-4_0:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2

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

docker pull stargateio/stargate-4_0:v1.0.57

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-3_11:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2

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

docker pull stargateio/stargate-3_11:v1.0.57

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-dse-68:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2

This image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground, along with a DataStax Enterprise^™ 6.8 backend.

docker pull stargateio/stargate-dse-68:v1.0.57

Run the Stargate Docker image

Cassandra 4.0
Cassandra 3.x
DSE 6.8

Use this docker-compose shell script to start the coordinator and APIs in developer mode. The easiest way to do that is to navigate to the <install_location>/stargate/docker-compose directory, and run the script. You will want to run, for example:

./start_cass_4_0_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

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=4.0 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-4_0:v1.0.57

./start_cass_3_11_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

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:v1.0.57

./start_dse_68_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

Start the Stargate container in developer mode. Developer mode removes the need to set up a separate DSE 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=6.8 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-dse-68:v1.0.57

Generate an authorization token to access the interface by following the instructions in Table-based authentication/Authorization

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.

Create or delete keyspace and table schema

In order to use the REST API, you must create schema that defines at least one keyspace and one table 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 each have a name and a defined data type. Multiple tables are contained in a keyspace, but a table cannot be contained in multiple keyspaces. If you are connecting to a Cassandra database with existing schema, you can skip this step.

For keyspaces, an optional setting, replicas, defines the number of data replicas the database will store for the keyspace. If no replica is defined, then for a keyspace in a single datacenter cluster, the default is 1, and for a multiple-datacenter cluster, the default is 3 for each datacenter.

Create a keyspace

Simple keyspace

Send a POST request to /v2/schemas/keyspaces. In this example we use users_keyspace for the name, and no replicas setting, to default to 1.

cURL command (/v2)
Result

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

{"name":"users_keyspace"

The authorization token and the content type are passed with --header. The token must be identified as X-Cassandra-Token so that cluster recognizes the token and its value. The specified name for the keyspace is passed as JSON data using --data. For shorthand, cURL can use -L for --location, -X for --request, -H for --header, and -d for --data.

Check keyspace existence

To check if a keyspaces exist, execute a REST API query with cURL to find all the keyspaces:

cURL command (/v2)
Result

curl -s -L -X GET http://localhost:8082/v2/schemas/keyspaces \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

{
  "data":[
    {
      "name":"system_distributed"
    },
    {
      "name":"system"
    },
    {
      "name":"data_endpoint_auth"
    },
    {
      "name":"users_keyspace"
    },
    {
      "name":"system_schema"
    },
    {
      "name":"test"
    },
    {
      "name":"stargate_system"
    },
    {
      "name":"library"
    },
    {
      "name":"system_auth"
    },
    {
      "name":"system_traces"
    }
  ]
}

To get a particular keyspace, specify the keyspace in the URL:

cURL command (/v2)
Result

curl -s -L -X GET http://localhost:8082/v2/schemas/keyspaces/users_keyspace \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

{"data":{"name":"users_keyspace"}}

Create a table in your keyspace

Create tables in your database using the Stargate REST API. Use the application token you generated to create a table in your keyspace. A keyspace is like a bucket that holds your tables. You can create different keyspaces for groups of tables.

After generating an authorization token, run the following request to get all available keyspaces and verify that the keyspace you wish to use is listed in the results:

Check keyspace existence

To check if a keyspaces exist, execute a REST API query with cURL to find all the keyspaces:

cURL command (/v2)
Result

curl -s -L -X GET http://localhost:8082/v2/schemas/keyspaces \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

{
  "data":[
    {
      "name":"system_distributed"
    },
    {
      "name":"system"
    },
    {
      "name":"data_endpoint_auth"
    },
    {
      "name":"users_keyspace"
    },
    {
      "name":"system_schema"
    },
    {
      "name":"test"
    },
    {
      "name":"stargate_system"
    },
    {
      "name":"library"
    },
    {
      "name":"system_auth"
    },
    {
      "name":"system_traces"
    }
  ]
}

To get a particular keyspace, specify the keyspace in the URL:

cURL command (/v2)
Result

curl -s -L -X GET http://localhost:8082/v2/schemas/keyspaces/users_keyspace \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

{"data":{"name":"users_keyspace"}}

For example, we’ll use users_keyspace as the keyspace.

Optional: A header line using a {unique-UUID}, a randomly-generated UUID that is unique for the authorization request, can be included in the previous command by adding the following line:

 --header 'x-cassandra-request-id: {unique-UUID}'

Create 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 in the --data field.

cURL command (/v2)
Result

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

{"name":"users"}

The name of our example table is users. This table column definition includes:

Partition key: One or more columns required. firstname is the partition key.
Clustering key: Optional, but zero, one or more columns can be defined. lastname is the clustering key.
Non-primary key: Optional, but zero, one or more columns that are not a partition key or clustering key can be defined. favorite_color is the non-primary key column.

Notice that each column must have a data type specified.

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

Optional: Table options can be set. The two options are:

defaultTimeToLive: Sets the default Time-To-Live (TTL).
clusteringExpression: Defines the order, either ascending (ASC) or descending (DESC) for columns that are clustering keys. ASC is the default.

  "tableOptions":
    {
      "defaultTimeToLive": 0,
      "clusteringExpression":
        [{ "column": "lastname", "order": "ASC" }]
    }

Check table and column existence

To check if a table exists, execute a REST API query with cURL to find all the tables:

cURL command (/v2)
Result

curl -s -L -X GET http://localhost:8082/v2/schemas/keyspaces/users_keyspace/tables \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

{
  "data": [
    {
      "name": "users",
      "keyspace": "users_keyspace",
      "columnDefinitions": [
        {
          "name": "firstname",
          "typeDefinition": "varchar",
          "static": false
        },
        {
          "name": "lastname",
          "typeDefinition": "varchar",
          "static": false
        },
        {
          "name": "email",
          "typeDefinition": "varchar",
          "static": false
        },
        {
          "name": "favorite color",
          "typeDefinition": "varchar",
          "static": false
        }
      ],
      "primaryKey": {
        "partitionKey": [
          "firstname"
        ],
        "clusteringKey": [
          "lastname"
        ]
      },
      "tableOptions": {
        "defaultTimeToLive": 0,
        "clusteringExpression": [
          {
            "order": "Asc",
            "column": "lastname"
          }
        ]
      }
    }
  ]
}

In this case, we only have one table in the keyspace.

To get a particular table, specify the table in the URL:

cURL command (/v2)
Result

curl -s -L \
-X GET http://localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

{
  "data": {
    "name": "users",
    "keyspace": "users_keyspace",
    "columnDefinitions": [
      {
        "name": "firstname
        "typeDefinition": "varchar",
        "static": false
      },
      {
        "name": "lastname",
        "typeDefinition": "varchar",
        "static": false
      },
      {
        "name": "current_country",
        "typeDefinition": "frozen<tuple<varchar, date, date>>",
        "static": false
      },
      {
        "name": "email",
        "typeDefinition": "varchar",
        "static": false
      },
      {
        "name": "evaluations",
        "typeDefinition": "map<int, varchar>",
        "static": false
      },
      {
        "name": "favorite color",
        "typeDefinition": "varchar",
        "static": false
      },
      {
        "name": "favorite_books",
        "typeDefinition": "set<varchar>",
        "static": false
      },
      {
        "name": "top_three_tv_shows",
        "typeDefinition": "list<varchar>",
        "static": false
      }
    ],
    "primaryKey": {
      "partitionKey": [
        "firstname"
      ],
      "clusteringKey": [
        "lastname"
      ]
    },
    "tableOptions": {
      "defaultTimeToLive": 0,
      "clusteringExpression": [
        {
          "order": "ASC",
          "column": "lastname"
        }
      ]
    }
  }
}

Although this command is slightly different, because we have only one table, the command to get all tables and this command to just get the table users return the same information.

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 command (/v2)
Result

curl -s --location --request POST 'http://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 -s --location --request POST 'http://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"
}'

{"firstname":"Mookie","lastname":"Betts"}
{"firstname":"Janesha","lastname":"Doesha"}

Notice that, unlike schema creation, data queries do not require tables in the URI, only the {tableName}.

Read data

Let’s check that the data was inserted. Send a GET request to /v2/keyspaces/{keyspace_name}/{table_name}?where={searchPath} to retrieve the two users that were entered:

cURL command (/v2)
Result

curl -s -L -G 'http://localhost:8082/v2/keyspaces/users_keyspace/users' \
   -H "X-Cassandra-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   --data-urlencode 'where={
     "firstname": {"$in": ["Janesha","Mookie"]}
   }'

{
  "count": 2,
  "data": [
    {
      "firstname": "Janesha",
      "evaluations": [
        { "key": 2019,
          "value": "okay"
        },
        {
          "key": 2020,
          "value": "good"
        }        
        ],
      "top_three_tv_shows": [
        "The Magicians",
        "The Librarians",
        "Agents of SHIELD"
      ],
      "favorite color": "grey",
      "current_country": [
        "France", 
        "2023-05-22T10:21:00.000Z",
        "2023-05-23T10:21:00.000Z"
      ],
      "email": "janesha.doesha@gmail.com",
      "lastname": "Doesha",
      "favorite_books": [
        "Emma",
        "The Color Purple"
      ]
    },
    {
      "firstname": "Mookie",
      "evaluations": [],
      "top_three_tv_shows": [],
      "favorite color": "blue",
      "current_country": null,
      "email": "mookie.betts.new-email@email.com",
      "lastname": "Betts",
      "favorite_books": []
    }
  ]
}

This query uses $in to find the two users. The WHERE clause can be used with other valid search terms: $eq, $lt, $lte, $gt, $gte, $ne, and $exists, if applicable. The primary key of the table can be used in the WHERE clause, but non-primary key columns cannot be used unless indexed.

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 command (/v2)
Result

curl -s -L -X PUT 'http://localhost:8082/v2/keyspaces/users_keyspace/users/Mookie/Betts' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
    "email": "mookie.betts.new-email@email.com"
}'

{"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}/{primaryKey}. For this example, the primary key consists of a partition key firstname and clustering column lastname, so we delete all data with Mookie/Betts:

curl -s -L -X DELETE http://localhost:8082/v2/schemas/keyspaces/users_keyspace/users/Mookie/Betts \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H "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 API references section.