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 haven’t already, create a database using Astra DB. |
You can create an Astra DB database using Astra Portal or the DevOps API. Currently, there are no drivers or other APIs that support creating a database. |
-
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.
Before you get started, set your environment variables to save time developing on your database. There are four environment variables, three of which you will get from the Astra dashboard (database id, region, and keyspace), and one that you must create (token).
-
In Astra DB, select the database to which you want to connect.
-
In your Database Dashboard, select Connect.
-
Select your API.
If you have multiple regions, select the region you want to connect to from the dropdown menu for instructions.
-
Follow the steps to get your application token and set up your environment variables. Or if you have an older Astra Classic database, follow the steps in Authentication for classic databases.
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 a table in your keyspace
Create tables in your database using the DataStax Astra DB 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.
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 /api/rest/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 -s --location \
--request POST https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/schemas/keyspaces/users_keyspace/tables \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_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 primary keys (partition keys and clustering keys) are found in the Cassandra Query Language (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 -s -L -X GET https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/schemas/keyspaces/users_keyspace/tables \
-H "X-Cassandra-Token: $ASTRA_DB_APPLICATION_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 -s -L \
-X GET https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/schemas/keyspaces/users_keyspace/tables/users \
-H "X-Cassandra-Token: $ASTRA_DB_APPLICATION_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 -s --location --request POST 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/schemas/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 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/schemas/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 -s -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/schemas/keyspaces/users_keyspace/users?where=\{"firstname":\{"$in":\["Janesha","Mookie"\]\}\}' \
-H "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
-H "Content-Type: application/json"
-H "Accept: application/json" \
--data-urlencode 'where={
"firstname": {"in": ["Janesha","Mookie"]}
}'
{
"count": 2,
"data": [
{
"firstname": "Janesha",
"evaluations":
{
"2019" : "okay",
"2020" : "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 -s -L -X PUT 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/schemas/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 https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/schemas/keyspaces/users_keyspace/users/Mookie/Betts \
-H "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
-H "Content-Type: application/json"
Voila! For more information on the REST API, see the Using the REST API or the REST API in the API references section.