Get started with the Astra DevOps API
The DevOps API is a REST API that you can use for organization and database administration in Astra DB Serverless.
Prerequisites
To use the DevOps API, you need the following:
-
An active Astra account.
-
A tool to handle API calls, such as curl.
Form DevOps API requests
DevOps API requests are typical RESTful API requests:
curl -sS -L -X METHOD "https://api.astra.datastax.com/v2/ENDPOINT_PATH" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{REQUEST_BODY}'DevOps API requests include the following components:
-
METHOD: The request method, such asPOST,GET,PUT, orDELETE. -
ENDPOINT_PATH: The target endpoint, which can include path parameters or query parameters.The endpoint path typically describes the action or object being targeted, for example:
-
POST /v2/tokensgenerates an application token. -
POST /v2/databases/DATABASE_ID/secureBundleURLgenerates a URL to download a database’s Secure Connect Bundle (SCB).
-
-
APPLICATION_TOKEN: The authorization header requires an application token with sufficient permissions to authorize the desired operation.For most DevOps API requests, the Organization Administrator role is more than sufficient. For automation and stricter access control, consider using other roles with narrower scopes. For more information, see the following:
-
REQUEST_BODY: Adatabody in the form of a JSON object, if required by the endpoint and method.The body schema can vary significantly across endpoints, and different endpoints can use the same parameter name for different values. For example,
namecan refer to the name of a database, role, or organization, depending on the endpoint.
Export environment variables
As you use the DevOps API, you will frequently reuse common values, such as application tokens, database IDs, and organization IDs.
Store these values in environment variables to facilitate reuse in your scripts, simplify token rotation, and increase security by keeping sensitive information separate from your core application code. DataStax recommends that you follow industry best practices when storing sensitive values, such as application tokens.
You can use any method you prefer to set environment variables, for example:
export ASTRA_DB_APPLICATION_TOKEN=APPLICATION_TOKEN
export ASTRA_DB_ID=DATABASE_IDFor information about storing and using environment variables in scripts, see the documentation for your preferred language or operating system.
Optional curl arguments
The DevOps API curl examples throughout the Astra DB Serverless documentation include some optional arguments, such as -s, -sS, and | jq.
You can omit or modify these arguments as needed.
Filepaths assume *nix
Throughout the Astra DB Serverless documentation, filepaths assume a *nix environment.
If you use Microsoft Windows, you might need to adjust the filepaths given in the examples.
DevOps API endpoints
The DevOps API provides endpoints for organization and database administration.
Access control endpoints
You can use the DevOps API to manage access to databases and other resources in your organization, including application tokens, users, roles, and IP access lists. For private endpoints, custom domains, and customer keys, see Private link and encryption endpoints.
- Roles and users
-
You can use the DevOps API to manage roles and manage users in your Astra DB organizations, including:
-
Creating, editing, and deleting custom roles
-
Creating custom roles with more granular permissions than are available in the Astra Portal.
-
Adding and removing users
-
Changing users' assigned roles
-
- Application tokens
-
You can use the DevOps API to manage application tokens, and you can get your organization ID from an application token.
- Access lists
-
You can use the DevOps API to manage IP access lists for databases and the IP access list for the DevOps API.
- Secure Connect Bundle
-
You can use the DevOps API to download Secure Connect Bundles for your databases.
Database endpoints
- Create and delete databases
-
Use the DevOps API to create databases and delete databases.
- Get database information
-
Use the DevOps API to get information about all databases in an organization or get information about one database.
Get all database IDs
You can use the DevOps API List databases endpoint to get all database IDs at once:
curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Accept: application/json"Make sure the application token has View DB permission for all relevant databases. For example, the Organization Administrator role can view all databases within an Astra DB organization. If the supplied token doesn’t have permission to view a particular database, the response won’t include any information for that database.
Response
A successful response contains an array of database objects. In each object, the
idfield contains the database ID.The following example is truncated for clarity.
[ { "id": "FIRST_DB_ID", "orgId": "organizations/ORG_ID", "ownerId": "users/ADMIN_USER_ID", "info": { ... }, "creationTime": "2012-11-01T22:08:41+00:00", "terminationTime": "2019-11-01T22:08:41+00:00", "status": "ACTIVE", "storage": { ... }, "availableActions": [ ... ], ... }, { "id": "SECOND_DB_ID", "orgId": "organizations/ORG_ID", "ownerId": "users/ADMIN_USER_ID", "info": { ... }, "creationTime": "2012-11-01T22:08:41+00:00", "terminationTime": "2019-11-01T22:08:41+00:00", "status": "ACTIVE", "storage": { ... }, "availableActions": [ ... ], ... } ] - Multi-region databases
-
Use the DevOps API to manage regions for multi-region databases.
- Keyspaces
-
Use the DevOps API to create and delete keyspaces in your databases.
Private link and encryption endpoints
- Private endpoints
-
Use the DevOps API to configure private endpoints for Astra DB databases.
- Custom domains
-
Use the DevOps API to configure custom domains for your Astra DB organization.
- Customer keys
-
Use the DevOps API to configure customer managed encryption keys.
Telemetry endpoints
You can use the DevOps API Telemetry endpoints to export database health metrics and stream Astra DB Serverless audit logs.
Other DevOps API endpoints
The DevOps API supports both Astra DB Serverless and Classic databases. Some endpoints are for Astra DB Classic databases only, such as the Resize and VPC Peering endpoints. For information about these endpoints, see the DevOps API reference.
DevOps API status codes
The DevOps API can return the following status codes:
200 OK 201 Created 202 Accepted 400 Bad request 401 Unauthorized 403 Forbidden 404 Not found 409 Conflict 500 Server error
Error responses include additional information about the specific error conditions.
