Using the Stargate REST API
Stargate is a data gateway deployed between client applications and a database. 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
If you are looking to just get started, DataStax Astra Database-as-a-Service can get you started with no install steps. |
Pull the Docker image
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.0
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:v1.0.0
The ports align to the following services and interfaces:
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 |
Swagger UI for the REST API
Once you have started the docker container, you can access the REST API
in a browser at localhost:8082/swagger-ui
.
Adding parameter information, you can generate cURL
commands to execute and
display results that will return.
Using the Auth API to generate an auth token
In order to use the Stargate REST 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 or dropping 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.
Creating a keyspace
Simple keyspace
Send a POST
request to /v2/schemas/keyspaces
.
In this example we use user_keyspace
for the name
, and no replicas
setting, to default to 1.
curl --location --request POST '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
.
Set replicas in simple keyspace
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
.
Keyspace for multiple datacenters
For a multiple-datacenter cluster, a keyspace is defined datacenters
.
Send a POST
request to /v2/schemas/keyspaces
.
In this example we use users_keyspace-dcs
for the name
, the datacenters are dc1
and dc2
,
where dc1
defaults to 3 replicas and dc2
is set to 5 replicas.
curl -L -X POST 'localhost:8082/v2/schemas/keyspaces' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "users_keyspace_dcs",
"datacenters": [ {"name": "dc1"}, {"name": "dc2", "replicas": 5} ]
}'
{"name":"users_keyspace_dcs"}
curl -L -X POST 'localhost:8082/v2/schemas/keyspaces' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "users_keyspace_dcs",
"datacenters": [ {"name": "dc1"}, {"name": "dc2", "replicas": 5} ]
}'
Checking keyspace existence
To check if a keyspaces exist, execute a
REST API query with cURL
to find all the keyspaces:
curl -L -X GET 'localhost:8082/v2/schemas/keyspaces' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json'
{
"data":[
{
"name":"system_distributed"
},
{
"name":"system"
},
{
"name":"data_endpoint_auth"
},
{
"name":"users_keyspace"
},
{
"name":"system_schema"
},
{
"name":"myworld"
},
{
"name":"stargate_system"
},
{
"name":"library"
},
{
"name":"users_keyspace2"
},
{
"name":"system_auth"
},
{
"name":"system_traces"
}
]
}
To get a particular keyspace, specify the keyspace in the URL:
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": "favorite color",
"typeDefinition": "text"
}
],
"primaryKey":
{
"partitionKey": ["firstname"],
"clusteringKey": ["lastname"]
},
"tableOptions":
{
"defaultTimeToLive": 0,
"clusteringExpression":
[{ "column": "lastname", "order": "ASC" }]
}
}'
{"name":"users"}
Information about partition keys and clustering keys are found in the CQL reference.
Adding columns to table schema
If you need to add an attribute to something you are storing in a table, you
can add a column by sending a POST
request to add the column.
curl -L -X POST 'localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns' \
-H 'X-Cassandra-Token: $AUTH_TOKEN' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"name": "email",
"typeDefinition": "text"
}'
{ "name": "email" }
To change the name or data type of an existing column, use a similar command, but
sent a PUT
request instead:
Checking table and column existence
To check if a table exists, execute a
REST API query with cURL
to find all the tables:
curl -L -X GET 'localhost:8082/v2/schemas/keyspaces/users_keyspace/tables' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-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"
}
]
}
}
]
}
To get a particular table, specify the table in the URL:
curl -L \
-X GET 'localhost:8082/v2/schemas/keyspaces/'users_keyspace'/tables/users' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-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"
}
]
}
}
}
To check if a column exists, execute a
REST API query with cURL
to find all the columns:
curl -L \
-X GET 'localhost:8082/v2/schemas/keyspaces/'users_keyspace'/tables/users/columns' \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "X-Cassandra-Token: $AUTH_TOKEN"
{
"data":[
{
"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
}
]
}
To get a particular column, specify the column in the URL:
curl -L \
-X GET 'localhost:8082/v2/schemas/keyspaces/'users_keyspace'/tables/users/columns/email' \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "X-Cassandra-Token: $AUTH_TOKEN"
{
"data":{
"name":"email",
"typeDefinition":"varchar",
"static":false
}
}
Drop keyspaces, tables or columns
Dropping a keyspace
Send a DELETE
request to /v2/schemas/keyspaces/{keyspace_name}
to delete
a keyspace. All data and all table schema will be deleted along with the
keyspace scheam.
curl --location \
--request DELETE 'localhost:8082/v2/schemas/keyspaces/users_keyspace' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json"
Dropping a table
Send a DELETE
request to /v2/schemas/keyspaces/{keyspace_name}/tables/{table_name}
to delete a table. All data will be deleted along with the table schema.
curl --location \
--request DELETE 'localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header "Content-Type: application/json"
Removing columns from table schema
If you find an attribute is no longer required in a table, you
can remove a column by sending a DELETE
request to delete the column. All
column data will be deleted along with the column schema.
curl --location
--request DELETE 'localhost:8082/v2/schemas/keyspaces/users_keyspace/tables/users/columns/email'
--header "X-Cassandra-Token: $AUTH_TOKEN"
--header "Content-Type: application/json"
Interacting with data stored in tables
All data written with the REST API is stored in columns in tables that were specified with the schema.
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"
}'
{"firstname":"Mookie","lastname":"Betts"}
{"firstname":"Janesha","lastname":"Doesha"}
Notice that, unlike schema creation, data queries do not require |
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 -L -X GET 'http://localhost:8082/v2/keyspaces/users_keyspace/users?where=\{"firstname":\{"$in":\["Janesha","Mookie"\]\}\}' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json'
{
"count":2,
"data":[
{
"firstname":"Janesha",
"favorite color":"grey",
"email":"janesha.doesha@gmail.com",
"lastname":"Doesha"
},
{
"firstname":"Mookie",
"favorite color":"blue",
"email":"mookie.betts@gmail.com",
"lastname":"Betts"
}
]
}
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.
A query for table rows must include a |
Send a GET
request to /v2/keyspaces/{keyspace_name}/{table_name}
to retrieve the row for Mookie
using $eq
:
curl -L -X GET 'http://localhost:8082/v2/keyspaces/users_keyspace/users?where=\{"firstname":\{"$eq":"Mookie"\}\}' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
"count":1,
"data":[
{
"firstname":"Mookie",
"favorite color":"blue",
"email":"mookie.betts@gmail.com",
"lastname":"Betts"
}
]
}
Finally, a primary key can be supplied to retrieve a row:
curl -L -X GET 'localhost:8082/v2/keyspaces/users_keyspace/users/Mookie/Betts' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json'
{
"count":1,
"data":[
{
"firstname":"Mookie",
"favorite color":"blue",
"email":"mookie.betts@gmail.com",
"lastname":"Betts"
}
]
}
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 -L -X PUT '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. |
It is also possible to update only part of a row. To partially update, send
a PATCH
request to /v2/keyspaces/{keyspace_name}/{table_name}/{path}
.
In this example, we realize we should not have changed the email address, and
we want to only change that one column:
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 -L -X DELETE 'localhost:8082/v2/keyspaces/users_keyspace/users/Mookie/Betts' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json'