# Data API builder integration

<Badge text="⭐ Community Toolkit" variant="tip" size="large" />

<Image
  src={dabIcon}
  alt="Data API builder logo"
  width={100}
  height={100}
  class:list={'float-inline-left icon'}
  data-zoom-off
/>

This article is the reference for the Aspire Data API Builder hosting integration. It enumerates the AppHost APIs that you use to model a [Data API Builder](https://learn.microsoft.com/azure/data-api-builder/overview) (DAB) resource in your [`AppHost`](/get-started/app-host/) project. DAB is an open-source tool that generates REST and GraphQL APIs directly from your database schema.

## Installation

To start building an Aspire app that uses Data API Builder, install the [📦 CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder) NuGet package:

```bash title="Terminal"
aspire add CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder
```

<LearnMore>
  Learn more about [`aspire add`](/reference/cli/commands/aspire-add/) in the command reference.
</LearnMore>

Or, choose a manual installation approach:

```csharp title="C# — AppHost.cs"
#:package CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder@*
```

```xml title="XML — AppHost.csproj"
<PackageReference Include="CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder" Version="*" />
```

```bash title="Terminal"
aspire add CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder
```

<LearnMore>
  Learn more about [`aspire add`](/reference/cli/commands/aspire-add/) in the command reference.
</LearnMore>

This updates your `aspire.config.json` with the Data API Builder hosting integration package:

```json title="aspire.config.json" ins={3}
{
  "packages": {
    "CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder": "*"
  }
}
```

The TypeScript AppHost bindings for Data API Builder are provided by the Community Toolkit package. After installation, the `.aspire/modules/aspire.mjs` file in your project includes `addDataAPIBuilder` and related APIs.

## Add Data API Builder resource

Once you've installed the hosting integration in your AppHost project, you can add a Data API Builder resource and reference a database as shown in the following example:

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var sqldb = builder.AddSqlServer("sql")
    .AddDatabase("sqldb");

var dab = builder.AddDataAPIBuilder("dab")
    .WithReference(sqldb);

builder.AddProject<Projects.ExampleProject>("example-project")
    .WithReference(dab);

// After adding all resources, run the app...
builder.Build().Run();
```

```typescript title="TypeScript — apphost.mts"
import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const sqldb = await (await builder.addSqlServer("sql")).addDatabase("sqldb");

const dab = await builder.addDataAPIBuilder("dab");
await dab.withReference(sqldb);

const exampleProject = await builder.addProject(
    "example-project",
    "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(dab);

// After adding all resources, run the app...
```

The Data API Builder integration automatically discovers and uses `dab-config.json` configuration files in your project.

## Multiple configuration files

Data API Builder supports multiple configuration files for different databases. To specify multiple configuration files, pass an array of config file paths to `AddDataAPIBuilder` or `addDataAPIBuilder`:

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
    .AddDatabase("sqldb");

var postgres = builder.AddPostgres("postgres")
    .AddDatabase("postgresdb");

var dab = builder.AddDataAPIBuilder("dab", ["dab-config.SqlServer.json", "dab-config.PostgreSQL.json"])
    .WithReference(sql)
    .WithReference(postgres);

// After adding all resources, run the app...
builder.Build().Run();
```

```typescript title="TypeScript — apphost.mts"
import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const sql = await (await builder.addSqlServer("sql")).addDatabase("sqldb");
const postgres = await (await builder.addPostgres("postgres")).addDatabase("postgresdb");

const dab = await builder.addDataAPIBuilder("dab", {
    configFilePaths: ["dab-config.SqlServer.json", "dab-config.PostgreSQL.json"],
});
await dab.withReference(sql);
await dab.withReference(postgres);

// After adding all resources, run the app...
```

## Custom container images

To use a custom Data API Builder container image, use the container image methods:

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var dab = builder.AddDataAPIBuilder("dab")
    .WithImageRegistry("myregistry.azurecr.io")
    .WithImage("custom-dab")
    .WithImageTag("1.0.0");

// After adding all resources, run the app...
builder.Build().Run();
```

```typescript title="TypeScript — apphost.mts"
import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const dab = await builder.addDataAPIBuilder("dab");
await dab.withImageRegistry("myregistry.azurecr.io");
await dab.withImage("custom-dab");
await dab.withImageTag("1.0.0");

// After adding all resources, run the app...
```

## Database references

Data API Builder requires references to the databases it exposes. Use `WithReference` or `withReference` to connect Data API Builder to your databases:

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
    .AddDatabase("sqldb");

var cosmos = builder.AddAzureCosmosDB("cosmos")
    .AddDatabase("cosmosdb");

var dab = builder.AddDataAPIBuilder("dab")
    .WithReference(sql)
    .WithReference(cosmos);

// After adding all resources, run the app...
builder.Build().Run();
```

```typescript title="TypeScript — apphost.mts"
import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const sql = await (await builder.addSqlServer("sql")).addDatabase("sqldb");
const cosmos = await (await builder.addAzureCosmosDB("cosmos")).addCosmosDatabase("cosmosdb");

const dab = await builder.addDataAPIBuilder("dab");
await dab.withReference(sql);
await dab.withReference(cosmos);

// After adding all resources, run the app...
```

## Configuration file structure

Data API Builder uses `dab-config.json` files to define the API. The following is an example configuration:

```json title="JSON — dab-config.json"
{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql"
    }
  },
  "entities": {
    "Product": {
      "source": "dbo.Products",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        }
      ]
    }
  }
}
```

The Aspire integration automatically injects the database connection strings from the referenced resources into the running container.

## Endpoints

Data API Builder exposes two endpoints:

- **REST API**: Available at `/api` by default
- **GraphQL API**: Available at `/graphql` by default

Both endpoints are configured in the `dab-config.json` file.

## See also

- [Data API Builder documentation](https://learn.microsoft.com/azure/data-api-builder/)
- [Data API Builder GitHub repository](https://github.com/Azure/data-api-builder)
- [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire)
- [Aspire integrations overview](/integrations/overview/)
- [Aspire GitHub repo](https://github.com/microsoft/aspire)