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, offering streamlined access to the functionalities provided by the Data API, whether deployed within Astra environments or on-premise DataStax Enterprise installations.

This client aims to simplify interactions with the Data API through a user-friendly, high-level API design. It supports fluent API patterns, builder mechanisms for complex configurations, and employs idiomatic method naming conventions to enhance readability and ease of use. The design philosophy of this client closely mirrors that of the established MongoDB API, providing a familiar experience to developers accustomed to MongoDB's client interface.

Through this client, users can perform a wide range of operations, from basic data manipulation in databases and collections to more advanced administrative tasks. Administrative capabilities, such as database creation and namespace management, are available to users with the appropriate administrative privileges.

Example usage:

 
 // Initialize the client with default settings
 DataAPIClient client = new DataAPIClient("yourAuthTokenHere");

 // Initialize the client with custom HTTP configuration
 DataAPIClient clientWithCustomConfig = new DataAPIClient("yourAuthTokenHere", DataAPIOptions.builder()
                 .withHttpRequestTimeout(1000) // Request timeout in milliseconds
                 .withHttpConnectTimeout(10) // Connection timeout in milliseconds
                 .withHttpVersion(HttpClient.Version.HTTP_2) // HTTP protocol version
                 .withDestination("ASTRA") // Target destination, e.g., Astra
                 .build());
This documentation highlights the ease of starting with the DataAPIClient, whether opting for a quick setup with default configurations or a more tailored approach via detailed HTTP client settings. The examples demonstrate both the straightforward initialization process and the method to apply fine-grained configurations for developers' specific needs.

  • Constructor Details

    • DataAPIClient

      public DataAPIClient(String token)
      Constructs a DataAPIClient instance using the specified authentication token. This constructor initializes the client with default DataAPIOptions 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 DataAPIOptions 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:

       
 String myAuthToken = "AstraCS:...";
 DataAPIClient client = new DataAPIClient(myAuthToken);
 // Now the client is ready to make authenticated requests with default settings
      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, DataAPIOptions 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 DataAPIOptions 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:

       
 String myAuthToken = "AstraCS:...";
 DataAPIOptions myOptions = DataAPIOptions.builder()
      .withHttpRequestTimeout(1000)
      .withHttpConnectTimeout(500)
      .withHttpVersion(HttpClient.Version.HTTP_2)
      .build();

 DataAPIClient myClient = new DataAPIClient(myAuthToken, myOptions);
 // The client is now ready to perform actions with custom configurations.
      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 DataAPIOptions 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.

  • Method Details

    • getAdmin

      public AstraDBAdmin getAdmin()
      Retrieves an administration client specific to Astra deployments. This client is intended for performing administrative tasks such as creating databases. It requires the use of a token with sufficient privileges.

      To use this method effectively, the provided authentication token must be associated with a user having elevated privileges, such as a Database Administrator or Organization Administrator. This ensures that the client has the necessary permissions to execute administrative operations within the Astra environment.

      The administration client provides a programmatic interface for managing various aspects of the Astra deployment, enabling tasks such as database creation, user management, and configuration adjustments without the need for direct interaction with the Astra UI.

      Example usage:

       
 DataAPIClient apiClient = new DataAPIClient("AstraCS:your_admin_token_here");
 AstraDBAdmin adminClient = apiClient.getAdmin();
 // Use adminClient to perform administrative operations, e.g., create a database
      Returns:
      An instance of AstraDBAdmin configured with the current authentication token, ready for administrative operations.
      Throws:
      SecurityException - if the current token does not have the necessary administrative privileges.

    • getAdmin

      public AstraDBAdmin getAdmin(String superUserToken)
      Retrieves an administration client capable of performing CRUD operations on databases, requiring a token with advanced privileges. This method is designed for scenarios where administrative access is necessary beyond the default token capabilities associated with the DataAPIClient.

      The provided superUserToken should be granted sufficient privileges to perform administrative operations, such as creating, updating, and deleting databases. This typically involves tokens associated with roles like Database Administrator or Organization Administrator within the Astra environment.

      Utilizing this method allows for direct access to the Astra database's administrative functionalities, enabling comprehensive management capabilities through the returned AstraDBAdmin client. This includes but is not limited to database creation, modification, and deletion.

      Example usage:

       
 String superUserToken = "AstraCS:super_user_token_here";
 DataAPIClient apiClient = new DataAPIClient(superUserToken);
 AstraDBAdmin adminClient = apiClient.getAdmin(superUserToken);
 // Now you can use adminClient for administrative operations like creating a database
      Parameters:
      superUserToken - A token with elevated privileges, enabling administrative actions within the Astra environment. This token must be authorized to perform operations such as creating and managing databases.
      Returns:
      An instance of AstraDBAdmin, configured for administrative tasks with the provided user token.
      Throws:
      SecurityException - if the provided superUserToken lacks the necessary privileges for administrative operations.

    • getDatabase

      public Database getDatabase(UUID databaseId, String namespace)
      Retrieves a client for a specific database, enabling interactions with the Data API. This method allows for operations such as querying, updating, and managing data within the specified database and namespace.

      The databaseId parameter is a unique identifier for the target database. This ID ensures that operations performed through the returned client are executed against the correct database instance within the Astra environment or an on-premise DataStax Enterprise setup.

      The namespace parameter specifies the namespace (often synonymous with "keyspace" in Cassandra terminology) within the database to which the client will have access. Namespaces are used to organize and isolate data within the database, providing a layer of abstraction and security.

      Example usage:

       
 UUID databaseId = UUID.fromString("your-database-uuid-here");
 String namespace = "your_namespace_here";
 DataAPIClient apiClient = new DataAPIClient("yourAuthTokenHere");
 Database databaseClient = apiClient.getDatabase(databaseId, namespace);
 // Use databaseClient to perform data operations within the specified namespace
      Parameters:
      databaseId - The unique identifier of the database to interact with.
      namespace - The namespace within the specified database to which operations will be scoped.
      Returns:
      A Database client configured to interact with the specified database and namespace, allowing for data manipulation and query operations.

    • getDatabase

      public Database getDatabase(UUID databaseId, String namespace, String region)
      Retrieves a client for a specific database, enabling interactions with the Data API. This method allows for operations such as querying, updating, and managing data within the specified database and namespace.
      Parameters:
      databaseId - The unique identifier of the database to interact with.
      namespace - The namespace associated to this database
      region - The cloud provider region where the database is deployed.
      Returns:
      A Database client configured to interact with the specified database and namespace, allowing for data manipulation and query operations.

    • getDatabase

      public Database getDatabase(UUID databaseId)
      Retrieves a client for interacting with a specified database using its unique identifier. This client facilitates direct communication with the Data API, enabling a range of operations such as querying, inserting, updating, and deleting data within the database. This streamlined method provides access to the default namespace or keyspace.

      The databaseId serves as a unique identifier for the database within the Astra environment or an on-premise DataStax Enterprise setup, ensuring that all operations through the client are correctly routed to the intended database instance.

      Example usage:

       
 UUID databaseId = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 DataAPIClient apiClient = new DataAPIClient("yourAuthTokenHere");
 Database databaseClient = apiClient.getDatabase(databaseId);
 // Perform data operations using the databaseClient
      Parameters:
      databaseId - The unique identifier of the database for which to retrieve the client.
      Returns:
      A Database client that provides the ability to perform operations on the specified database.

    • getDatabase

      public Database getDatabase(String apiEndpoint, String namespace)
      Creates and returns a database client configured to interact with the Data API at the specified API endpoint and within the given namespace. This method facilitates operations such as querying, inserting, updating, and deleting data by directly communicating with the Data API, allowing for a wide range of data manipulation tasks in a specified namespace.

      The apiEndpoint parameter should be the URL of the API endpoint where the Data API is hosted. This is typically a fully qualified URL that points to the Astra service or an on-premise DataStax Enterprise deployment hosting the Data API.

      The namespace parameter specifies the namespace (or keyspace in Cassandra terms) within the database that the client will interact with. Namespaces help organize data within the database and provide a way to isolate and manage access to data.

      Example usage:

       
 String apiEndpoint = "https://example-astra-data-api.com";
 String namespace = "my_keyspace";
 DataAPIClient apiClient = new DataAPIClient("yourAuthTokenHere");
 Database databaseClient = apiClient.getDatabase(apiEndpoint, namespace);
 // Now you can use the databaseClient to perform operations within "my_keyspace"
      Parameters:
      apiEndpoint - The URL of the Data API endpoint. This specifies the location of the API the client will connect to.
      namespace - The namespace (or keyspace) within the database that the client will access and perform operations in.
      Returns:
      A Database client configured for the specified API endpoint and namespace, enabling data manipulation and query operations within the targeted namespace.

    • getDatabaseAdmin

      public DatabaseAdmin getDatabaseAdmin(String apiEndpoint)
      Retrieves a client for interacting with a specified database using its unique identifier.
      Parameters:
      apiEndpoint - apiEndpoint for the database.
      Returns:
      an instance of Database admin

    • getDatabaseAdmin

      public AstraDBDatabaseAdmin getDatabaseAdmin(UUID databaseId)
      Retrieves a client for interacting with a specified database using its unique identifier.
      Parameters:
      databaseId - database identifier
      Returns:
      the database admin if exists

    • getDatabase

      public Database getDatabase(String apiEndpoint)
      Retrieves a database client configured to interact with the Data API at the specified API endpoint. This method enables direct communication with the Data API, facilitating a range of data manipulation operations such as querying, inserting, updating, and deleting data. The client accesses the default namespace or keyspace for operations, unless otherwise specified through additional configuration.

      The apiEndpoint parameter should be the URL of the Data API endpoint you wish to connect to. This URL points to the location where the Data API is hosted, which could be an Astra cloud service or an on-premise DataStax Enterprise instance.

      Utilizing this method simplifies the process of connecting to the Data API by focusing on essential configuration, making it particularly useful for scenarios where detailed namespace management is handled separately or not required.

      Example usage:

       
 String apiEndpoint = "https://<database_id>-<database_region>.apps.astra.datastax.com";
 DataAPIClient apiClient = new DataAPIClient("yourAuthTokenHere");
 Database databaseClient = apiClient.getDatabase(apiEndpoint);
 // The databaseClient is now ready to perform data operations at the specified API endpoint
      Parameters:
      apiEndpoint - The URL of the Data API endpoint to connect to, specifying the API's location.
      Returns:
      A Database client tailored for interaction with the Data API at the provided API endpoint, ready for executing data manipulation tasks.