Stargate Document 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 Document 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 Document API, you must create schema that defines the namespace
and collections that will store the data. A namespace is a container for which a
replication factor
defines the number of data replicas the database will store.
Collections consist of unstructured JSON documents. Documents can themselves
hold multiple documents. Multiple collections are contained
in a namespace, but a collection cannot be contained in multiple namespaces.
Checking namespace existence
To check if a namespaces exist, execute a
Document API query with cURL
to find all the namespaces:
curl -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com//api/rest/v2/schemas/namespaces' \
-H "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
-H 'Content-Type: application/json'
{"data":[{"name":"system_distributed"},{"name":"system"},
{"name":"data_endpoint_auth"},{"name":"system_schema"},{"name":"myworld"},
{"name":"stargate_system"},{"name":"system_auth"},{"name":"system_traces"}]}
To get a particular namespace, specify the namespace in the URL:
Interacting with data stored in collections
Writing documents
All data written with the Document API is stored as JSON documents stored in collections.
For more information about the database design of the Document API, see the blog post on the Documents API. |
Add document specifying a collection name
First, let’s add a document to a specified collection.
Send a POST
request to /api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}
to add data to the collection fitness
.
The data is passed in the JSON body.
curl --location \
--request POST 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
"id": "some-stuff",
"other": "This is nonsensical stuff."
}'
{"documentId":"3ffc7ae6-c42d-46de-b52b-b5e77ae6a87b"}
Notice that the document-id
returned is a UUID if not specified.
Add document specifying collection name and document-id
Next, let’s add a document to a specified collection, but specify the document-id
.
Send a PUT
request to
/api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}
to add data to the collection Janet
.
The document-id
can be any string.
The data is passed in the JSON body.
curl -L -X PUT 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/Janet' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
"firstname": "Janet",
"lastname": "Doe",
"email": "janet.doe@gmail.com",
"favorite color": "grey"
}'
{"documentId":"Janet"}
Note the difference between using POST
and PUT
. The POST
request
is used to insert new documents when you want the system to auto-generate the
documentId. The PUT
request is used to insert a new document when you want to
specify the documentId.
PUT
requests can also be used to update an existing
document. Let’s look at those examples, next.
For more information about the database design of the Document API, see the blog post on the Documents API. |
Retrieving a specified document
Let’s check that the data was inserted for a particular document.
Send a GET
request to /api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}
to retrieve the document:
curl -L \
-X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/3ffc7ae6-c42d-46de-b52b-b5e77ae6a87b' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"documentId":"3ffc7ae6-c42d-46de-b52b-b5e77ae6a87b",
"data":{
"id":"some-stuff",
"other":"This is nonsensical stuff."
}
}
It is possible to get a value for a particular field in a document using one of
two methods, either a where
clause or a document-path
. These methods can
retrieve information from a document or a sub-document.
Retrieving a document using a where clause
Now let’s search for a particular document using a where
clause.
Send a GET
request to
/api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}?{where-clause}
to get the same information:
curl -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?where=\{"firstname":\{"$eq":"Janet"\}\}' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"data":{
"Janet":{
"email":"janet.doe@gmail.com",
"favorite color":"grey",
"firstname":"Janet",
"lastname":"Doe"
}
}
}
Note that the where
clause must be url encoded, so curly brackets are escaped
with \
and spaces must be replaced with %20
.
Also, the full document is returned, as opposed to the value of the field specified in the
{document-path}
like the next command.
Update documents
Data changes, so often it is necessary to update an entire document.
Replace a document
Send a PATCH
request to
/api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}
to replace data to the existing collection. All fields included will be changed.
curl -L \
-X PATCH 'lhttps://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/Janet' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
"firstname": "JanetLee",
"lastname": "Doe"
}'
{"documentId":"Janet"}
A GET
request will show that the data has been replaced in the document:
curl -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/Janet' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"documentId":"Janet",
"data":{
"email":"janet.doe@gmail.com",
"favorite color":"grey",
"firstname":"JanetLee",
"lastname":"Doe"
}
}
PATCH updates are upserts. If the document doesn’t exist, it will be created.
If it does exist, it will be updated with the new document data.
|
Delete a document
To delete a document, send a DELETE
request to
/api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}
.
curl -L \
-X DELETE 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/3ffc7ae6-c42d-46de-b52b-b5e77ae6a87b' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
Voila! For more information on the Document API, see the Using the Document API or the Document API in the API references section.