Home

Overview

This SDK (Software Development Kit) makes it easy to call Stargate and/or Astra services using idiomatic Java APIs. On top of clients for the different API, the SDK provides a Spring Boot starter to ease integration with Spring Applications.

overview of the SDK coverage

Installation

You need JDK 11.0.9+ and a dependency management tool such as Maven or Gradle. (The SDK has been build with the HttpClient provided in JDK 11) It is a single library providing support for the 5 API(s) listed above. Please change the SDK-version with the latest version.

Maven dependency in pom.xml

<dependency>
  <groupId>com.datastax.astra</groupId>
  <artifactId>astra-sdk</artifactId>
  <version>${SDK-version}</version>
</dependency>

Gradle dependency in build.gradle

dependencies {
    astra_sdk 'com.datastax.astra:astra-sdk:${sdk-version}'
}

Initialising SDK to work with Astra

📘 (a) Prerequisite: Setup Astra your Instance

You will need an Astra account and some credentials (Astra Token). Based on the provided parameters the underlying Apis will be enabled or not. (devops, rest data, rest document graphQL, pulsar client)

Please follow those 2 tutorials to set up your Astra instance:

• Create an Astra instance
• Create an Astra token

📘 (b) Setup AstraClient object

AstraClient client = AstraClient.builder()
 .databaseId("astra_cluster_id")           // Unique identifier for your database instance
 .cloudProviderRegion("astra_db_region")   // Cloud Provider region picked for you instance
 .keyspace("ks1")                          // (optional) Set your keyspace

 .appToken("AstraCS:......")               // App Token will be used as ApiKey for Devops, Docs and REST Api.
 .clientId("TWRvjlcrgfZYfhcxGZhUlAAA")     // Will be used as your username
 .clientSecret("7xKSrZPLbWxDJ0WXyj..")     // Will be used as your password

 .secureConnectBundle("/tmp/sec.zip")      // (optional) if not provided download in ~/.astra
 .build();

📘 (c) Overview of parameters for AstraClient.builder

Param Name	DevOps API	REST and Docs API	GraphQL API	CqlSession API	Pulsar Client
appToken (part of token)	required	required	required	--	required
clientId (part of token)	optional	--	--	required	--
clientSecret (part of token)	optional	--	--	required	--
databaseId	--	required	required	required	--
database Cloud Region	--	required	required	required	--
keyspace	--	--	--	optional	--
Secure Connect Bundle	--	--	--	optional	--

Initialising the SDK with Local Stargate

Astra is not required to work with the SDK. A standalone installation of Stargate exposes Rest,Document, Graph Apis but also the CqlSession.

📘 (a) Setup Stargate Instance

To install Stargate on your environment please check out the following guide

Instead of the token shown for Astra, you will use a user and a password and will authenticate against a dedicated authenticationUrl. Make sure to create a user at the Cassandra level and enable RBAC.

📘 Setup StargateClient wrapper

StargateClient client = StargateClient.builder()
  .username("k8ssandra-superuser")           // Mandatory username
  .password("JxzrPOnvDGqfEOQ0EySQ")          // Mandatory password
  .endPointAuth("http://localhost:8081")     // Mandatory authencation url, defaulting to http://localhost:8081
  .endPointRest("http://localhost:8082")     // Rest and Document Apis
  .endPointGraphQL("http://localhost:8080")  // GraphQL Api
  
  // Cqlsession Only
  .addCqlContactPoint("127.0.0.", 9042)      // Contact Point
  .localDc("dc1")                            // Local Datacenter is mandatory driver 4x+
  .keypace("ks1")                            // (optional) Set your keyspace
  .build();

📘 Overview of parameters for StargateClient.builder

Param Name	REST and Doc APIs	GraphQL API	CqlSession API
username	required	required	required
password	required	required	required
Authentication endpoint	required	required	required
Rest Api endpoint	required	--	--
GraphQL Api endpoint	--	required	--
Contact Points	--	--	required
Local DataCenter Name (localDc)	--	--	required
keyspace	--	--	optional

Load configuration

To setup the SDK you can provide values using the builder as listed above but not only. You can use some environment variables, jvm parameters (-DXXX=YYY) or load some configuration file (.astrarc)

**📘 (a) Work with ~/.astrarc **

This file uses the ini configuration formatting. A key ASTRA_DB_APPLICATION_TOKEN is associated to its value. Values are grouped in sections identified by a [name].

Sample File with 2 sections:

[default]
ASTRA_DB_APPLICATION_TOKEN=AstraCS:GmSdU.....
ASTRA_DB_CLIENT_ID=GmSdUgw....
ASTRA_DB_CLIENT_SECRET=pL7QcZgN....
ASTRA_DB_ID=33a7527a-aaf9-4f9f-9758-96216efff3d5
ASTRA_DB_KEYSPACE=ks1
ASTRA_DB_REGION=eu-central-1
ASTRA_DB_SECURE_BUNDLE=

[sandbox]
ASTRA_DB_APPLICATION_TOKEN=AstraCS:GmSdU.....
ASTRA_DB_CLIENT_ID=GmSdUgw....
ASTRA_DB_CLIENT_SECRET=pL7QcZgN....
ASTRA_DB_ID=33a7527a-aaf9-4f9f-9758-96216efff3d5
ASTRA_DB_KEYSPACE=ks1
ASTRA_DB_REGION=eu-central-1
ASTRA_DB_SECURE_BUNDLE=

The file starts with a [default] section. If nothing name is provided it will be the one to load. In the SDK this file will be associated with the class com.datastax.astra.sdk.utils.AstraRc

• Generate an ~/.astrarc

// Generate the file in default location user home (~/.astrarc) 
AstraRc.create("<your_token>");
        
// Generate the file in a defined location
AstraRc.create("<your_token>", new File("/tmp/astracrc"));

• **Load an ~/.astrarc file **