Compare Data API client versions
DataStax recommends using the latest versions of the clients to access the newest features, improvements, and bug fixes.
This page describes major changes in specific client versions, including major new features, deprecations, removals, and breaking changes. This page does not provide client release notes.
For information about the latest client versions, installation and upgrade instructions, and other client documentation, see the links in the following table:
| Language | Client | Version | Dependency | Documentation |
|---|---|---|---|---|
|
Python 3.8 or later |
|||
|
Node.js 18 or later |
|||
|
Java 11 or later |
Version 1.5
DataStax released clients version 1.5 and Data API version 1.0.16 on September 20, 2024.
Deprecation of namespace
Version 1.5 of the Data API clients deprecates namespace in favor of keyspace.
In this version, you can use either keyspace or namespace, but you must use one consistently.
This change also applies to the Data API itself (HTTP).
This change aligns the Data API and clients with the DevOps API, which already uses keyspace for both namespaces and keyspaces.
It also better reflects the underlying Astra DB functionality, in which namespace is effectively an alternative label for keyspace.
|
A future client release will remove support for |
After you upgrade to version 1.5, change your code to use keyspace instead of namespace.
For example:
-
Python
-
TypeScript
-
Java
-
curl
# Before 1.5
database = client.get_database("API_ENDPOINT", namespace="NAMESPACE_OR_KEYSPACE_NAME")
# 1.5 and later
database = client.get_database("API_ENDPOINT", keyspace="NAMESPACE_OR_KEYSPACE_NAME")// Before 1.5
const db = client.db('API_ENDPOINT', { namespace: 'NAMESPACE_OR_KEYSPACE_NAME' });
// 1.5 and later
const db = client.db('API_ENDPOINT', { keyspace: 'NAMESPACE_OR_KEYSPACE_NAME' });// Before 1.5
Database db = client.getDatabase(String apiEndpoint, String namespace);
// 1.5 and later
Database db = client.getDatabase(String apiEndpoint, String keyspace);The impact to HTTP requests is minimal.
HTTP already accepted either a keyspace or namespace name in the URL path, and most commands used a keyspace parameter.
curl -sS --location -X POST "ASTRA_DB_ENDPOINT/api/json/v1/NAMESPACE_OR_KEYSPACE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{DATA_API_COMMAND_BODY}'Astra DB Serverless documentation and client references use keyspace in place of namespace, with the following exceptions:
-
Some preexisting integration guides and tutorials that rely on a subcomponent, such as a sample app, that is unrelated to the Data API and has a
namespaceobject, class, variable, or otherwise. -
Third-party documentation over which DataStax has no influence.
Deprecation of id and region to specify a database
In version 1.5.1 and later of the Python and TypeScript clients, the API_ENDPOINT is the preferred way to use a DataAPIclient to get a database.
The API_ENDPOINT inherently includes the database’s ID and region.
As a result, the alternative ID and REGION syntax is deprecated.
|
A future client release will remove support for this usage of This deprecation does not apply to the following:
|
After you upgrade to version 1.5.1 or later, change your astrapy and astra-db-ts code to use API_ENDPOINT instead of ID and REGION.
-
Python
-
TypeScript
-
Java
-
curl
Change your client.get_database commands to use API_ENDPOINT, instead of ID and REGION.
The following examples show multiple versions of the same command. An actual script would use only one.
# Before 1.5.1, the following are all valid:
database = client.get_database("API_ENDPOINT")
database = client.get_database("ID")
database = client["API_ENDPOINT"]
database = client["ID"]
database = client.get_database("API_ENDPOINT", keyspace="KEYSPACE_NAME")
database = client.get_database("ID", keyspace="KEYSPACE_NAME", region="REGION")
# At 1.5.1 and later, use only 'API_ENDPOINT':
database = client.get_database("API_ENDPOINT")
database = client["API_ENDPOINT"]
database = client.get_database("API_ENDPOINT", keyspace="KEYSPACE_NAME")Change your client.db commands to use API_ENDPOINT, instead of ID and REGION.
The following examples show multiple versions of the same command. An actual script would use only one.
// Before 1.5.1, the following are all valid:
const db = client.db('API_ENDPOINT');
const db = client.db('ID', 'REGION');
const db = client.db('API_ENDPOINT', { keyspace: 'KEYSPACE_NAME' });
const db = client.db('ID', 'REGION', { keyspace: 'KEYSPACE_NAME' });
// At 1.5.1 and later, use only 'API_ENDPOINT':
const db = client.db('API_ENDPOINT');
const db = client.db('API_ENDPOINT', { keyspace: 'KEYSPACE_NAME' });This deprecation does not apply to the Java client.
You can continue to use either API_ENDPOINT or ID and REGION:
// The following are all valid before and after 1.5.1:
Database db = client.getDatabase(String apiEndpoint);
Database db = client.getDatabase(UUID databaseId, String region);
Database db = client.getDatabase(String apiEndpoint, String keyspace);
Database db = client.getDatabase(UUID databaseId, String region, String keyspace);This deprecation does not apply to HTTP, which already exclusively uses the API endpoint as the basis of the URL path, such as:
curl -sS --location -X POST "ASTRA_DB_ENDPOINT/api/json/v1/KEYSPACE_NAME"