Build your API with DAB. Build your client with Kiota!

Jerry Nixon

Project Kiota is a code generation engine from Microsoft that reads the OpenAPI specification emitted from any REST endpoint and then creates reusable client code in CSharp, Go, Java, PHP, Python, Ruby, Swift, and TypeScript. Kiota is a byproduct of Microsoft Graph, a sophisticated REST endpoint that required developers to write boilerplate code over and over – but not with Kiota. In the same way that the Data API builder (DAB) says, “Don’t waste your time writing API code for your data,” Kiota says, “Don’t waste time writing client code for your API.” A perfect friendship of technologies.

Build your API with DAB

Data API builder (DAB) is an open-source engine that runs in a container. With only a JSON configuration file that describes your SQL Server, Azure SQL, Cosmos DB, PostgreSQL, or MySQL database, it automatically generates both REST and GraphQL endpoints. The engine comes with a comprehensive family of built-in developer tools like OpenAPI, Swagger, and Banana Cake Pop, as well as enterprise features such as security, caching, monitoring, and stateless scalability. It doesn’t matter if you are running DAB on-premises or in the cloud, as a private endpoint or public, against a single table or a thousand, Data API builder is fastest and cleanest way to get a secure, feature-rich API running.

Running Data API builder

The Data API builder configuration file (dab-config.json) has three key sections: data source, runtime, and entities. The Data Source section connects to your database. The Runtime section configures the engine & endpoints. The Entities section is where you list the tables, views and stored procedures you want to expose through REST or GraphQL endpoints. Read more in the docs: https://aka.ms/dab/docs.

dab start

This command is all you need to turn your configuration file into REST and GraphQL endpoints. The cross-platform Data API builder CLI also lets developers build & modify their configuration file through add & update commands. But “start” is the bread and butter to spin up a fully functional API on any development box. Of course, you can tweak DAB with environment variables and run the DAB container in Docker, but for most development, the CLI is all you really need.

Build your client with Kiota

Like Data API builder, Kiota also has a CLI (Command Line Interface) that allows developers to build out a solution. The DAB CLI is used to build the configuration file and run the engine. The Kiota CLI is used to generate source code in the language you use and the folder you want.

Kiota installs as a dotnet tool, just like Data API builder. Assuming you already have dotnet installed (you can use ‘winget install Microsoft.DotNet.SDK.7’) the command line can handle finding, downloading and installing the Kiota CLI for you.

dotnet tool install microsoft.openapi.kiota -g

Once installed, change to an empty working directory and start playing with the Kiota CLI. Because Kiota is deterministic, you can run it, delete the output, and run it again as many times as you want. It’s a great way to reason through the resulting code. In the .NET world, running the ‘generate’ command will create the files and folders intended for your class library referenced by the client. Having said that, nothing stops you from generating Kiota’s code directly in the client project, should separation of concerns & encapsulation be something you want to introduce later.

kiota generate -l csharp -d https://localhost:5001/api/openapi

This simple example accepts most of the defaults to illustrate how straightforward code generation can be. Additional switches include custom folders and namespaces to better fit into your codebase. The resulting files include a primary API client, custom response objects for every endpoint, and the models necessary to serialize and deserialize payloads. All of these are things you would need to build without Kiota. But why? This engine gives you a standard, proven, and repeatable approach to save you time and testing.

Handling SSL

There is possibility you will experience some trouble using the self-signed SSL certificate used by Data API builder in your development environment. As a simple workaround for using Kiota generate, you can download the OpenAPI data into a JSON file and point to your local file in the -d command. A more long-term solution is to trust localhost certificates on your box with the following commands:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Building the Kiota client

The CSharp code generated by Kiota isn’t the whole story. A lot of Kiota’s magic is in NuGet packages you will need to add to your project. Using the info command emits the different packages necessary to get your library or client working with Kiota.

C:\Temp\working>kiota info -l CSharp
The language CSharp is currently in Stable maturity level.
After generating code for this language, you need to install the following packages:
dotnet add package Microsoft.Kiota.Abstractions
dotnet add package Microsoft.Kiota.Http.HttpClientLibrary
dotnet add package Microsoft.Kiota.Serialization.Form
dotnet add package Microsoft.Kiota.Serialization.Json
dotnet add package Microsoft.Kiota.Authentication.Azure
dotnet add package Microsoft.Kiota.Serialization.Text
dotnet add package Microsoft.Kiota.Serialization.Multipart

Run these commands at the command line, manually add these references to your csproj file, or use the NuGet Manager in Visual Studio to update your project. Once you have the necessary libraries, you’ll be able to build the Kiota code and start using it. Here’s how your csproj might look.

<ItemGroup>
  <PackageReference Include="Microsoft.Kiota.Abstractions" Version="1.5.0" />
  <PackageReference Include="Microsoft.Kiota.Http.HttpClientLibrary" Version="1.2.0" />
  <PackageReference Include="Microsoft.Kiota.Serialization.Form" Version="1.1.0" />
  <PackageReference Include="Microsoft.Kiota.Serialization.Json" Version="1.1.1" />
  <PackageReference Include="Microsoft.Kiota.Serialization.Multipart" Version="1.1.0" />
  <PackageReference Include="Microsoft.Kiota.Serialization.Text" Version="1.1.0" />
</ItemGroup>

Code gen philosophy

It’s worth taking a moment to remind you that code generation is intended to be run and left alone. That is to say, other than to learn or review the code before you use it, opening the class files shouldn’t be part of your typical workflow. Why? Because it’s tempting to make changes. Code generation, at its best, can be run over and over without negatively impacting anything. If you introduce custom code into generated files, this can’t be done. For .NET developers, look into partial classes; this gives you some flexibility to modify generated classes if you just can’t resist.

Accessing your endpoint

While Data API builder is running (remember DAB is how you access the database) write your C# access code against the Kiota API client. To do this, you will need a IRequestAdapter, and to get that you’ll need an IAuthenticationProvider. Several of each is provided through the accompanying Kiota NuGet packages. Assuming the easiest path for our sample here, we’ll use the AnonymousAuthenticationProvider, to build an HttpClientRequestAdapter, to build the ApiClient. With that, you can access our sample Books, Authors, or any other valid endpoint specified in the OpenAPI document you provided during generation.

var authProvider = new AnonymousAuthenticationProvider();
var requestAdapter = new HttpClientRequestAdapter(authProvider)
{
    BaseUrl = "https://localhost:5001/api"
};
var apiClient = new ApiClient(requestAdapter);

var books = await apiClient.Books.GetAsync();
if (books?.Value?.Count > 0)
{
    foreach (var item in books.Value!)
    {
        Console.WriteLine(item.Title);
    }
}
else
{
    // handle no books
}

Conclusion

It works! You’ve saved yourself a lot of time and headache by using Data API Builder to generate your REST endpoints and expose your data sources. Why not continue the savings with Kiota? Generate the client code in the language you want. Generate proven and repeatable code to save your team development hours, testing, bug fixes, and a longer CI/CD pipeline. Both are free, both are open source, and both are built by engineers for engineers. Build your API with DAB; build your client with Kiota. Learn more about Kiota here.

Jerry Nixon Senior Program Manager, Azure SQL

Follow