Quickstart: Use Data API builder with NoSQL

In this Quickstart, you build a set of Data API builder configuration files to target the Azure Cosmos DB for NoSQL emulator.

Prerequisites

• Docker
• .NET 8

Tip

Alternatively, open this Quickstart in GitHub Codespaces with all developer prerequisites already installed. Simply bring your own Azure subscription. GitHub accounts include an entitlement of storage and core hours at no cost. For more information, see included storage and core hours for GitHub accounts.

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
   

Configure the local database

Start by running the local emulator. Then, you can seed a new container with sample data.

1. Get the latest copy of the mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest container image from Docker Hub.

   docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
   

2. Start the docker container by publishing port 8081 and the port range 10250-10255.

   docker run \
       --publish 8081:8081 \
       --publish 10250-10255:10250-10255 \
       --detach \
       mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
   

3. Download the self-signed certificate for the emulator

   curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt
   

4. Install the self-signed certificate using either the Bash steps for Linux, or the PowerShell steps for Windows.

   sudo cp ~/emulatorcert.crt /usr/local/share/ca-certificates/
   sudo update-ca-certificates
   

   certutil -f -addstore "Root" emulatorcert.crt
   

5. Connect to your local database using your preferred data management environment. Examples include, but aren't limited to: the Azure Databases extension for Visual Studio Code.

   Tip

   The default connection string for the emulator is AccountEndpoint=https://localhost:8081;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;.

6. Create a new bookshelf database and authors container.

7. Seed the container with this basic JSON data.

   [
     {
       "id": "01",
       "firstName": "Henry",
       "lastName": "Ross"
     },
     {
       "id": "02",
       "firstName": "Jacob",
       "middleName": "A.",
       "lastName": "Hancock"
     },
     {
       "id": "03",
       "firstName": "Sydney",
       "lastName": "Mattos"
     },
     {
       "id": "04",
       "firstName": "Jordan",
       "lastName": "Mitchell"
     },
     {
       "id": "05",
       "firstName": "Victoria",
       "lastName": "Burke"
     },
     {
       "id": "06",
       "firstName": "Vance",
       "lastName": "DeLeon"
     },
     {
       "id": "07",
       "firstName": "Reed",
       "lastName": "Flores"
     },
     {
       "id": "08",
       "firstName": "Felix",
       "lastName": "Henderson"
     },
     {
       "id": "09",
       "firstName": "Avery",
       "lastName": "Howard"
     },
     {
       "id": "10",
       "firstName": "Violet",
       "lastName": "Martinez"
     }
   ]
   

   Tip

   The method used to seed data will largely depend on the data management tool. For Azure Data Studio, you can save this JSON array as a .json file and then use the Import feature.

Create configuration files

Create a baseline configuration file using the DAB CLI. Then, add a development configuration file with your current credentials.

1. Create a new file named schema.graphql with this schema content.

   type Author @model {
     id: ID!
     firstName: String!
     middleName: String
     lastName: String!
   }
   

2. Create a typical configuration file using dab init. Add the --connection-string argument with the emulator's default connection string.

   dab init --database-type "cosmosdb_nosql" --host-mode "Development" --cosmosdb_nosql-database bookshelf --graphql-schema schema.graphql --connection-string "AccountEndpoint=https://localhost:8081;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;"
   

3. Add an Author entity using dab add.

   dab add Author --source "authors" --permissions "anonymous:*"
   

Test API with the local database

Now, start the Data API builder tool to validate that your configuration files are merged during development.

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

   dab start
   

2. The output of the tool should include the address to use to navigate to the running API.

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

   Tip

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

3. Go to the GraphQL endpoint by navigating to /graphql and running this operation.

   query {
     authors {
       items {
         id
         firstName
         lastName
       }
     }
   }
   

   Tip

   In this example, the URL would be https://localhost:5000/graphql. You can navigate to this URL using your web browser.

Next step

Quickstart: Deploy Data API builder to Azure