Rest API

AstraClient and Stargate initializations have been detailed on the Home page. Moving forward the sample code will reuse those classes but do not initialized them.

The Stargate REST API provides CRUD operations on top of Cassandra objects (tables, UDT, records). It was implemented to create an stateless absraction layer on top of Cassandra Query Language (CQL)

Related Api Reference documentation and endpoints can be found there

Class ApiDataClient is the core class to work with Rest DATA. There are multiple ways to retrieve or initialize it.

// Option1. Given an astraClient
ApiDataClient client1 = astraClient.apiStargateData();
ApiDataClient client2 = astraClient.getStargateClient().apiRest();

// Option 2. Given a StargateClient
ApiDataClient client3 = stargateClient.apiRest();

// Option 3. Constructors
ApiDataClient client4_Astra    = new ApiDataClient("http://api_endpoint", "apiToken");
ApiDataClient client5_Stargate = new ApiDataClient("http://api_endpoint", 
  new TokenProviderDefault("username", "password", "http://auth_endpoint");

From now, in another samples, we will use the variable name apiClient as our working instance of ApiDataClient

Working with keyspaces

DataApiIntegrationTest is the main unit test for this API and could be use as reference code

✅. Lists available Keyspace Names

Stream<String> keyspaceNames = apiClient.keyspaceNames();

✅. Lists available Keyspaces

Stream<Keyspace> keyspaces = apiClient.keyspaces();

✅. Find a keyspace by its id

Optional<Keyspace> ns1 = apiClient.keyspace("ks1").find();

✅. Test if a keyspace exists

apiClient.keyspace("ks1").exist();

✅. Create a new keyspace

🚨 As of Today, namespaces and keyspaces creations in ASTRA are available only at the DevOps API level but work in in a StandAlone stargate deployment

// Create a namespace with a single DC dc-1
DataCenter dc1 = new DataCenter("dc-1", 1);
apiClient.keyspace("ns1").create(dc1);

// Create a namespace providing only the replication factor
apiClient.keyspace("ns1").createSimple(3);

✅. Delete a keyspace

🚨 As of today namespaces and keyspaces creations are not available in ASTRA but work as expected with standalone stargate.

apiClient.keyspace("ns1").delete();

ℹ️ Tips

You can simplify the code by assigning apiClient.keyspace("ks1") to a KeyspaceClient variable as shown below:

KeyspaceClient ks1Client = astraClient.apiStargateData().keyspace("ns1");
        
// Create if not exist
if (!ks1Client.exist()) {
  ks1Client.createSimple(3);
}
        
// Show datacenters where it lives
ks1Client.find().get().getDatacenters()
         .stream().map(DataCenter::getName)
         .forEach(System.out::println); 
        
// Delete 
ks1Client.delete();

Working with Tables

✅. Lists available tables in namespace

// We can create a local variable to shorten the code.
KeyspaceClient ks1Client = apiClient.keyspace("ks1");

// List names of the tables
Stream<String> tableNames   = ks1Client.tableNames();

// List Definitions of the table (primarykey...)
Stream<TableDefinition> tableDefinitions = ks1Client.tables();

✅. Check if a table exists

TableClient tableXClient = apiClient.keyspace("ks1").table("table_x");
boolean colExist = tableXClient.exist();

✅. Retrieve a table definition from its name

Optional<TableDefinition> = apiClient.keyspace("ks1").table("table_x").find();

✅. Create a table

// Using a dedicated bean Create table
CreateTable tcr = new CreateTable();
tcr.setName("table_x");
tcr.setIfNotExists(true);
tcr.getColumnDefinitions().add(new ColumnDefinition("genre", "text"));
tcr.getColumnDefinitions().add(new ColumnDefinition("year", "int"));
tcr.getColumnDefinitions().add(new ColumnDefinition("title", "text"));
tcr.getColumnDefinitions().add(new ColumnDefinition("upload", "timestamp"));
tcr.getColumnDefinitions().add(new ColumnDefinition("tags", "set<text>"));
tcr.getColumnDefinitions().add(new ColumnDefinition("frames", "list<int>"));
tcr.getColumnDefinitions().add(new ColumnDefinition("tuples", "tuple<text,text,text>"));
tcr.getColumnDefinitions().add(new ColumnDefinition("formats", "frozen<map <text,text>>"));
tcr.getPrimaryKey().getPartitionKey().add("genre");
tcr.getPrimaryKey().getClusteringKey().add("year");
tcr.getPrimaryKey().getClusteringKey().add("title");
tcr.getTableOptions().getClusteringExpression().add(new ClusteringExpression("year", Ordering.DESC));
tcr.getTableOptions().getClusteringExpression().add(new ClusteringExpression("title", Ordering.ASC));
apiClient.keyspace("ks1").table("table_x").create(tcr);

Working with User Defined Types

Working with Tables