Package com.datastax.astra.client

Class DataAPIClient

java.lang.Object
com.datastax.astra.client.DataAPIClient
public class DataAPIClient extends Object
Serves as the primary entry point to the Data API client, providing an intuitive and streamlined interface for interacting with the Data API. The client is compatible with both Astra environments and on-premise DataStax Enterprise installations, offering flexibility across deployment scenarios.

The DataAPIClient is designed to simplify database interactions by providing:

  • A high-level, user-friendly API that adheres to fluent programming principles.
  • Support for builder patterns to accommodate complex client configurations.
  • Idiomatic method naming and design inspired by the MongoDB API, ensuring a familiar experience for developers.

This design philosophy facilitates quick onboarding and ease of use while enabling advanced customizations when needed.

Core Features:

  • Data manipulation capabilities for databases, collections, and tables.
  • Administrative operations, such as database and keyspace creation (requires appropriate privileges).
  • Support for destination-specific options, including Astra and DSE environments.

Example Usage:


 DataAPIClientOptions options = new DataAPIClientOptions()
         .destination(DataAPIDestination.DSE) // Set the destination
         .httpClientOptions(new HttpClientOptions()
                 .httpRedirect(HttpClient.Redirect.NORMAL) // Configure HTTP redirects
                 .httpProxy(new HttpProxy("localhost", 8080)) // Set up an HTTP proxy
                 .httpRetries(1, Duration.ofSeconds(10))) // Configure retries
         .timeoutOptions(new TimeoutOptions()
                 .requestTimeoutMillis(1000)) // Set request timeout
         .enableFeatureFlagTables() // Enable feature flag for tables
         .addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, "true"); // Add custom headers
 DataAPIClient client = new DataAPIClient("token", options);

  • Constructor Details

    • DataAPIClient

      public DataAPIClient(String token)
      Constructs a DataAPIClient instance using the specified authentication token. This constructor initializes the client with default DataAPIClientOptions for its configuration.

      The provided token is used for authenticating HTTP requests made by this client. It is essential for accessing secured resources. If specific HTTP configurations are required (e.g., custom timeouts, HTTP version), use the other constructor that accepts both a token and a DataAPIClientOptions instance.

      This constructor is suitable for scenarios where default client settings are sufficient and no advanced configuration is needed. It simplifies the initialization process for quick setup and use.

      Example usage:

       
 DataAPIClient client = new DataAPIClient("token");
      Parameters:
      token - The authentication token to be used for HTTP requests. This token should follow the format expected by the server, typically starting with "AstraCS:.." for Astra environments.

    • DataAPIClient

      public DataAPIClient(String token, DataAPIClientOptions options)
      Constructs a DataAPIClient with specified authentication token and HTTP client configuration options.

      This constructor allows for the explicit specification of both the authentication token and the advanced HTTP configuration settings. The authentication token is essential for securing access to the API, while the DataAPIClientOptions object provides granular control over the HTTP client's behavior, including timeouts, HTTP version, and other properties impacting connectivity and request handling.

      It is recommended to use this constructor when you need to customize the HTTP client beyond the default configuration, such as setting custom timeouts or specifying a particular HTTP protocol version. The provided Assert methods ensure that neither the token nor the options are null or empty, enforcing the presence of essential configuration details at the time of client initialization.

      Example usage:

       
 DataAPIClientOptions options = new DataAPIClientOptions()
         .destination(DataAPIDestination.DSE) // Set the destination
         .httpClientOptions(new HttpClientOptions()
                 .httpRedirect(HttpClient.Redirect.NORMAL) // Configure HTTP redirects
                 .httpProxy(new HttpProxy("localhost", 8080)) // Set up an HTTP proxy
                 .httpRetries(1, Duration.ofSeconds(10))) // Configure retries
         .timeoutOptions(new TimeoutOptions()
                 .requestTimeoutMillis(1000)) // Set request timeout
         .enableFeatureFlagTables() // Enable feature flag for tables
         .addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, "true"); // Add custom headers
 DataAPIClient client = new DataAPIClient("token", options);
      Parameters:
      token - The authentication token to be used for securing API access. This token should adhere to the format required by the API, typically starting with "AstraCS:.." for Astra environments.
      options - The DataAPIClientOptions specifying the detailed HTTP client configurations, offering customization over aspects such as timeouts and protocol versions.
      Throws:
      IllegalArgumentException - if the token is empty or null, or if the options are null.

    • DataAPIClient

      public DataAPIClient(DataAPIClientOptions options)
      Constructs a new instance of the DataAPIClient without a default token. The token will instead need to be specified when calling `.getDatabase()` or `.getAdmin()`. Prefer this method when using a db-scoped token instead of a more universal token.

      Example usage:

       
 DataAPIClientOptions options = new DataAPIClientOptions()
                 .timeoutOptions(new TimeoutOptions()
                     .connectTimeoutMillis(1000)
                     .requestTimeoutMillis(1000))
                 .httpClientOptions(new HttpClientOptions()
                     .httpVersion(HttpClient.Version.HTTP_2)
                 );
 DataAPIClient myClient = new DataAPIClient(myOptions);
 // The client is now ready to perform actions with custom configurations.
      Parameters:
      options - - The default options to use when spawning new instances of Database or AstraDBAdmin.

  • Method Details

    • getAdmin

      public AstraDBAdmin getAdmin(AdminOptions adminOptions)
      Retrieves an administration client specifically designed for Astra deployments. This client is used for performing administrative tasks such as database creation, user management, and configuration adjustments. It provides a programmatic interface for managing Astra resources securely and efficiently.

      This method has three variants, allowing for flexibility in token usage:

      To perform administrative tasks, the token must belong to a user with sufficient privileges (e.g., Database Administrator or Organization Administrator). If these conditions are not met, a SecurityException is thrown.

      Example usage:

       
 // Example 1: Using the default token provided at client initialization
 DataAPIClient apiClient = new DataAPIClient("AstraCS:your_admin_token_here");
 AstraDBAdmin adminClient = apiClient.getAdmin();
 adminClient.createDatabase("new_database", "keyspace_name");

 // Example 2: Using a custom super token for administrative operations
 AstraDBAdmin adminClientWithSuperToken = apiClient.getAdmin("AstraCS:your_super_admin_token_here");
 adminClientWithSuperToken.createDatabase("another_database", "another_keyspace");

 // Example 3: Using advanced options for fine-grained control
 AdminOptions options = new AdminOptions("AstraCS:custom_token", new DataAPIClientOptions().logRequests());
 AstraDBAdmin advancedAdminClient = apiClient.getAdmin(options);
 advancedAdminClient.createDatabase("custom_database", "custom_keyspace");
      Parameters:
      adminOptions - The options to configure the administration client, including the authentication token.
      Returns:
      An instance of AstraDBAdmin configured with the appropriate authentication token and options, ready for administrative operations.

    • getAdmin

      public AstraDBAdmin getAdmin()
      Retrieves an administration client using the default authentication token provided during DataAPIClient initialization.
      Returns:
      An instance of AstraDBAdmin configured with the default token.
      Throws:
      SecurityException - if the token does not have the necessary privileges or the operation is not in an Astra environment.
      See Also:

    • getAdmin

      public AstraDBAdmin getAdmin(String superToken)
      Retrieves an administration client using the default authentication token provided during DataAPIClient initialization.
      Parameters:
      superToken - The custom token to use for administrative operations.
      Returns:
      An instance of AstraDBAdmin configured with the default token.
      See Also:

    • getDatabase

      public Database getDatabase(String apiEndpoint, DatabaseOptions dbOptions)
      Retrieves a database client configured to interact with the Data API. This client enables direct communication with the specified Data API endpoint, supporting a wide range of data manipulation operations such as querying, inserting, updating, and deleting data.

      The getDatabase method has multiple variants to cater to different usage scenarios:

      By providing flexibility in how connections are established and configured, these methods simplify the process of interacting with Cassandra databases through the Data API. They are suitable for various deployment scenarios, including Astra cloud services and on-premise installations.

      Example usage:

       
 // Example 1: Connect using a direct API endpoint
 String apiEndpoint = "https://<database_id>-<database_region>.apps.astra.datastax.com";
 DataAPIClient apiClient = new DataAPIClient("yourAuthTokenHere");
 Database databaseClient = apiClient.getDatabase(apiEndpoint);

 // Example 2: Connect using a database ID (with automatic endpoint resolution)
 UUID databaseId = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 Database databaseClientById = apiClient.getDatabase(databaseId);

 // Example 3: Customize options while connecting
 DatabaseOptions options = new DatabaseOptions("yourAuthTokenHere", new DataAPIClientOptions().logRequests());
 Database customDatabaseClient = apiClient.getDatabase(apiEndpoint, options);
      Parameters:
      apiEndpoint - The URL of the Data API endpoint to connect to.
      dbOptions - The options to configure the database client.
      Returns:
      A Database client tailored for interaction with the Data API, configured according to the provided parameters.
      Throws:
      IllegalArgumentException - If the provided parameters are invalid or insufficient for resolving the endpoint.

    • getDatabase

      public Database getDatabase(String apiEndpoint, String keyspace)
      Retrieves a database client configured to connect to the Data API using the specified API endpoint and keyspace.

      Uses default DatabaseOptions for configuration.

      Parameters:
      apiEndpoint - The URL of the Data API endpoint to connect to.
      keyspace - The name of the keyspace to use for database operations.
      Returns:
      A Database client configured with default options for the specified endpoint and keyspace.
      See Also:

    • getDatabase

      public Database getDatabase(String apiEndpoint)
      Retrieves a database client configured to connect to the Data API using the specified API endpoint.

      Uses default DatabaseOptions for configuration.

      Parameters:
      apiEndpoint - The URL of the Data API endpoint to connect to.
      Returns:
      A Database client configured with default options for the specified endpoint.
      See Also:

    • getDatabase

      public Database getDatabase(UUID databaseId)
      Retrieves a database client configured to connect to the Data API using a database identifier.

      Automatically resolves the API endpoint based on the database ID and uses default DatabaseOptions.

      Parameters:
      databaseId - The unique identifier of the database.
      Returns:
      A Database client configured with default options for the resolved endpoint.
      See Also:

    • getDatabase

      public Database getDatabase(UUID databaseId, DatabaseOptions dbOptions)
      Retrieves a database client configured to connect to the Data API using a database identifier, with custom DatabaseOptions.

      Automatically resolves the API endpoint based on the database ID.

      Parameters:
      databaseId - The unique identifier of the database.
      dbOptions - The options to configure the database client.
      Returns:
      A Database client configured for the resolved endpoint and custom options.
      See Also:

    • getDatabase

      public Database getDatabase(UUID databaseId, String region, DatabaseOptions dbOptions)
      Retrieves a database client configured to connect to the Data API using a database identifier, a specified region, and custom DatabaseOptions.
      Parameters:
      databaseId - The unique identifier of the database.
      region - The region where the database is deployed (optional).
      dbOptions - The options to configure the database client.
      Returns:
      A Database client configured for the specified database ID, region, and options.
      See Also:

    • getToken

      public String getToken()
      Gets token
      Returns:
      value of token

    • getOptions

      public DataAPIClientOptions getOptions()
      Gets options
      Returns:
      value of options