Get started with the Data API (C#)

You can use the Data API to programmatically interact with your databases.

The Data API provides an entry point for application development with Hyper-Converged Database (HCD) databases, including a variety of generative AI ecosystem integrations. It leverages the scalability, performance, and real-time indexing capabilities of Apache Cassandra® to support generative AI application development.

If you are new to the Data API, check out the quickstart for collections or the quickstart for tables for a demo of some common commands.

Get endpoint and token

The Data API requires your database’s API endpoint and an application token.

Get endpoint

The Data API endpoint for your database has the form: http://CLUSTER_HOST:GATEWAY_PORT

Replace CLUSTER_HOST with the external IP address of any node in your cluster. To find this, run kubectl get nodes -o wide and use any of the values listed under "EXTERNAL-IP" in the output.
Replace GATEWAY_PORT with the port number for your API gateway service. To find this, run kubectl get svc and look for the "PORT(S)" value that corresponds to NodePort.

Generate token

The Data API requires an application token in the following format: Cassandra:BASE64-ENCODED_USERNAME:BASE64_ENCODED_PASSWORD. The username and password used to generate the token must be tied to a role that has sufficient permissions to perform the desired operations.

You set a username and password when you create a cluster.

If you didn’t provide superuser credentials when you created your cluster, they were generated automatically and saved in a superuser secret named CLUSTER_NAME-superuser. The CLUSTER_NAME-superuser secret contains both the username and the password.

You can use DataAPIClient.UsernamePasswordTokenProvider from the client to generate the token. Alternatively, you can build the token yourself.

using DataStax.AstraDB.DataApi;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    var token = DataAPIClient.UsernamePasswordTokenProvider(
      "USERNAME",
      "PASSWORD"
    );
  }
}

Use a client

DataStax provides several clients, including the C# client, to facilitate interaction with the Data API.

Install the client

Update to one of the following:
- .NET version 8 or later
- .NET Framework 4.6.2 or later
- .NET Standard 2.1 or later
Install the latest version of the astra-db-csharp package.
```
dotnet add package DataStax.AstraDB.DataApi
```

Use the client to interact with data

In general, all scripts that use a client will do the following:

Instantiate a DataAPIClient object.

All Data API interactions through a client start with a DataAPIClient object.
Connect to a database.

Most Data API interactions through a client require you to connect to a database through a DataAPIClient object.
Perform CRUD operations.

For example, you can create a collection or table, insert data, and find data. For a full list of operations, see the collection commands and table commands.

Here’s an example of a simple client script. For a more detailed demo, see the quickstart for collections and the quickstart for tables.

The following example uses untyped documents, but you can use strongly-typed classes for compile-time checks and IntelliSense. For more information and examples, see Custom typing for collections.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Get an existing collection
    var collection = database.GetCollection("COLLECTION_NAME");

    // Use vector search and filters to find a document
    var filterBuilder = Builders<Document>.CollectionFilter;
    var filter = filterBuilder.And(
      filterBuilder.Eq("is_checked_out", false),
      filterBuilder.Lt("number_of_pages", 300)
    );

    var findOptions = new CollectionFindOneOptions<Document>()
    {
      Sort = Builders<Document>.CollectionSort.Vector(
        new float[] { 0.08f, -0.62f, 0.39f }
      ),
    };

    var result = await collection.FindOneAsync(filter, findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

Use HTTP

Instead of using a client, you can make direct HTTP requests.