Manage Data with the Data API

The Data API uses semantic versioning. The full version number consists of 3 parts: major.minor.patch.

An update to the Data API may be a non-versioned bug fix, a patch update, a minor update, or a major update. When a non-versioned bug fix is released, the version number is not updated. When a patch update, a minor update, or a major update is released, the version number is updated also.

With few exceptions, new versions of Data API are backward compatible, minimizing the effect on existing deployments. In most cases, you do not have to update your existing infrastructure when a new version of the Data API is released. Features added in a new version of the Data API will not break existing deployments.

Exceptions to backward compatibility are as follows:

If your client app and your Capella cluster use the same cloud service provider (CSP), you can connect your client app to the Data API privately through the cloud, using either a VPC Peering connection or a private endpoint.

VPC Peering (virtual private cloud) provides a connection between your client app and the whole Capella cluster. A private endpoint provides a connection between your client app and the Data API in particular.

Both of these solutions add security by avoiding communication over the Internet, and may lead to a reduction in latency and egress costs.

The Data API uses cluster access credentials for authentication and authorization.

The access privileges specified for the cluster access credential determine the buckets, scopes, and collections that a client can access via the Data API.

You must permit access to the cluster from the IP address of the Data API client. (If you’re accessing the Data API via a VPC Peering connection or a private endpoint, you do not need to permit access from the peered range of private IP addresses.)

To authenticate a Data API call, you must pass the cluster access credentials as the username and password, using HTTP Basic authentication.

To support concurrent requests, PUT and DELETE requests support optimistic concurrency control, using If-Match headers in combination with HTTP ETags (entity tags). Exceptions are noted in the endpoint descriptions. A typical pattern is to do a GET request on a specified resource, which returns an ETag value. You can then include the ETag value in a PUT request to update the resource.

The ETag value for a document is equivalent to the document’s CAS (Compare and Swap) value.

The Data API provides passthrough access to the Query Service and the Search Service.

The passthrough Query Service endpoints enable you to run SQL++ queries and set request-level parameters. Managing and administrating the Query Service is not supported.

The passthrough Search Service endpoints enable you to run Full-Text Search queries and Vector Search queries using a Search index. Other search requests are not supported.

You can access the passthrough Query Service and Search Service endpoints via the Data API, in the same way as the other Data API endpoints.

You’ll incur charges when you enable the Data API for a cluster. You’ll incur an extra charge when both Data API and VPC Peering connections are enabled. Enabling private endpoint support with the Data API has no additional cost. For details of the charges associated with the Data API, see Manage Your Billing.