Data API builder integration

⭐ Community Toolkit

Data API Builder (DAB) is an open-source tool that provides a REST and GraphQL API on top of your database. The Aspire Data API Builder hosting integration enables you to run Data API Builder alongside your .NET projects in the Aspire app host.

Hosting integration

To get started with the Aspire Data API Builder hosting integration, install the CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder NuGet package in the app host project.

aspire add communitytoolkit-azure-dataapibuilder

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> communitytoolkit-azure-dataapibuilder (CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder)
> Other results listed as selectable options...

#:package CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder@*

<PackageReference Include="CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder" Version="*" />

Add Data API Builder resource

To add Data API Builder to your app host, use the AddDataAPIBuilder extension method:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.AddProject<Projects.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:

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...

Custom container images

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

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...

Database references

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

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...

Configuration file structure

Data API Builder uses dab-config.json files to define the API. Here’s an example configuration:

{
  "$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.

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.