Class DataAPIClient
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 Summary
ConstructorDescriptionDataAPIClient
(String token) Constructs aDataAPIClient
instance using the specified authentication token.DataAPIClient
(String token, DataAPIOptions options) Constructs aDataAPIClient
with specified authentication token and HTTP client configuration options. -
Method Summary
Modifier and TypeMethodDescriptiongetAdmin()
Retrieves an administration client specific to Astra deployments.Retrieves an administration client capable of performing CRUD operations on databases, requiring a token with advanced privileges.getDatabase
(String apiEndpoint) Retrieves a database client configured to interact with the Data API at the specified API endpoint.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.getDatabase
(UUID databaseId) Retrieves a client for interacting with a specified database using its unique identifier.getDatabase
(UUID databaseId, String namespace) Retrieves a client for a specific database, enabling interactions with the Data API.getDatabase
(UUID databaseId, String namespace, String region) Retrieves a client for a specific database, enabling interactions with the Data API.getDatabaseAdmin
(String apiEndpoint) Retrieves a client for interacting with a specified database using its unique identifier.getDatabaseAdmin
(UUID databaseId) Retrieves a client for interacting with a specified database using its unique identifier.
-
Constructor Details
-
DataAPIClient
Constructs aDataAPIClient
instance using the specified authentication token. This constructor initializes the client with defaultDataAPIOptions
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
Constructs aDataAPIClient
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
- TheDataAPIOptions
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
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
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 theDataAPIClient
.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 providedsuperUserToken
lacks the necessary privileges for administrative operations.
-
getDatabase
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
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 databaseregion
- 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
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
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
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
Retrieves a client for interacting with a specified database using its unique identifier.- Parameters:
databaseId
- database identifier- Returns:
- the database admin if exists
-
getDatabase
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.
-