ערוך

שתף באמצעות

Quickstart: Use Data API builder with SQL

In this quickstart, you create REST and GraphQL endpoints for a local SQL database using Data API builder (DAB). Choose your database engine to get started.

Prerequisites

Install the Data API builder CLI

Install the Microsoft.DataApiBuilder package from NuGet as a .NET tool.

  1. Use dotnet tool install to install the latest version of the Microsoft.DataApiBuilder with the --global argument.

    dotnet tool install --global Microsoft.DataApiBuilder

    Note

    If the package is already installed, update the package instead using dotnet tool update.

    dotnet tool update --global Microsoft.DataApiBuilder

  2. Verify that the tool is installed with dotnet tool list using the --global argument.

    dotnet tool list --global

Pull the database image

Tip

Already have a database? Skip to Create and seed the database, run the SQL script for your engine, then jump to Configure Data API builder with your own connection string.

Download the Docker image for your database engine. This step can take a few minutes depending on your connection speed.

docker pull mcr.microsoft.com/mssql/server:2025-latest

Start the database

Run a local database instance in Docker.

docker run --name dab-mssql --env "ACCEPT_EULA=Y" --env "MSSQL_SA_PASSWORD=P@ssw0rd1" --publish 1433:1433 --detach mcr.microsoft.com/mssql/server:2025-latest

Tip

If port 1433 is already in use (for example, by a local SQL Server installation), change --publish to a different host port like 1434:1433 and update Server=localhost,1433 to Server=localhost,1434 in later steps.

Verify the database engine is ready before running the next command.

docker exec dab-mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "P@ssw0rd1" -C -Q "SELECT 1"

If this returns an error, wait a few seconds and try again.

Create and seed the database

Create a todos database and table, then add sample data. If you're using Docker, no SQL client is needed—docker exec runs the commands directly inside the container. If you're using your own database, run the SQL script in your preferred tool.

  1. Create the database.

    docker exec dab-mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "P@ssw0rd1" -C -Q "CREATE DATABASE todos;"

  2. Create the table and add sample data.

    docker exec dab-mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "P@ssw0rd1" -C -d todos -Q "CREATE TABLE dbo.todos (id int PRIMARY KEY, title nvarchar(100) NOT NULL, completed bit NOT NULL DEFAULT 0); INSERT INTO dbo.todos VALUES (1, 'Walk the dog', 0), (2, 'Feed the fish', 0), (3, 'Comb the cat', 1);"

Tip

Using your own SQL Server? Run this script directly:

CREATE DATABASE todos;
GO
USE todos;
GO
CREATE TABLE dbo.todos (id int PRIMARY KEY, title nvarchar(100) NOT NULL, completed bit NOT NULL DEFAULT 0);
INSERT INTO dbo.todos VALUES (1, 'Walk the dog', 0), (2, 'Feed the fish', 0), (3, 'Comb the cat', 1);

Configure Data API builder

Create a DAB configuration file and add a Todo entity.

Tip

Using your own database? Replace the connection string in dab init with your own:

  • SQL Server: Server=<host>,<port>;Database=todos;User Id=<user>;Password=<password>;TrustServerCertificate=true;Encrypt=true;
  • PostgreSQL: Host=<host>;Port=5432;Database=todos;User ID=<user>;Password=<password>;
  • MySQL: Server=<host>;Port=3306;Database=todos;User=<user>;Password=<password>;

  1. Initialize the configuration.

    dab init --database-type "mssql" --host-mode "Development" --connection-string "Server=localhost,1433;Database=todos;User Id=sa;Password=P@ssw0rd1;TrustServerCertificate=true;Encrypt=true;"

  2. Add the Todo entity.

    dab add Todo --source "dbo.todos" --permissions "anonymous:*"

Your dab-config.json file should now look similar to the following example:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/vmajor.minor.patch/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=localhost,1433;Database=todos;User Id=sa;Password=P@ssw0rd1;TrustServerCertificate=true;Encrypt=true;"
  },
  "runtime": {
    "rest": {
      "enabled": true
    },
    "graphql": {
      "enabled": true
    },
    "host": {
      "mode": "development",
      "cors": {
        "origins": ["*"]
      }
    }
  },
  "entities": {
    "Todo": {
      "source": "dbo.todos",
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            "*"
          ]
        }
      ]
    }
  }
}

Tip

You can skip the dab init and dab add commands and create the dab-config.json file directly with the content shown here.

Start the API

Use dab start to run the tool and create API endpoints for your entity.

dab start

The output should include the address of the running API.

      Successfully completed runtime initialization.
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: <http://localhost:5000>

Tip

In this example, the application is running on localhost at port 5000. Your running application may have a different address and port.

Test the API

  1. Open your browser and navigate to the REST endpoint for the Todo entity.

    http://localhost:5000/api/Todo

  2. The JSON response should include all three todo items.

    {
  "value": [
    { "id": 1, "title": "Walk the dog", "completed": false },
    { "id": 2, "title": "Feed the fish", "completed": false },
    { "id": 3, "title": "Comb the cat", "completed": true }
  ]
}

  3. Navigate to the Swagger documentation page at /swagger.

    http://localhost:5000/swagger

Build a web app

Display your todos in a browser using a plain HTML file. Create a file named todo.html using either the REST or GraphQL endpoint.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Todo App</title>
  <style>
    body { font-family: sans-serif; max-width: 400px; margin: 2rem auto; }
    li.done { text-decoration: line-through; color: gray; }
    #error { color: red; }
  </style>
</head>
<body>
  <h1>Todos</h1>
  <ul id="list"></ul>
  <p id="error"></p>
  <script>
    fetch('http://localhost:5000/api/Todo')
      .then(r => r.json())
      .then(data => {
        const ul = document.getElementById('list');
        data.value.forEach(todo => {
          const li = document.createElement('li');
          li.textContent = todo.title;
          if (todo.completed) li.className = 'done';
          ul.appendChild(li);
        });
      })
      .catch(() => {
        document.getElementById('error').textContent =
          'Could not reach the API. Make sure DAB is running on http://localhost:5000.';
      });
  </script>
</body>
</html>

Open todo.html in your browser. The page fetches all todo items and renders them as a list, with completed items shown in strikethrough.

Important

The cors setting in your configuration allows this HTML file—opened from your local file system—to call the API. Without it, the browser blocks the request.

Clean up

Stop and remove the Docker container when you're done.

docker stop dab-mssql && docker rm dab-mssql

Next step

REST endpoints

  • Last updated on