Build API clients with Microsoft Kiota

Service-oriented architectures are at the heart of modern application development. By building applications out of a mix of services, we can take advantage of the current generation of platforms to build serverless, scalable, distributed applications. Microsoft has long been at the forefront of API-first design and development, with low-level tools to build and deliver APIs.

A key part of Microsoft’s API strategy is the OpenAPI description language. Based on Swagger, OpenAPI makes it easy to build applications that have self-describing APIs, delivering descriptions as a standard build artifact, alongside binaries. Having that API description is useful, as tools like Visual Studio can consume the description and build a scaffolding for clients to use with HTTP APIs. But what if you’re building code with a tool or a language that’s not supported?

I was looking at the documentation for the latest release of the Teams SDK and saw a reference to an open source tool called Project Kiota to add HTTP API support. The GitHub repository for Kiota shows that it’s a standalone CLI-based tool for working with OpenAPI descriptions. It supports many popular languages, including Dart, Go, and Ruby. The status page shows work underway for Swift and TypeScript, as the underlying framework is designed to quickly add new language support.

Understanding Project Kiota

Microsoft says the aim of the project is “to eliminate the need to take a dependency on a different API client library for every API that you need to call.” The underlying intent is that you don’t need to learn a new REST library for each language you use; you can instead rely on generated methods and objects. Kiota provides a basic set of tools for serializing and deserializing JSON payloads.

Usefully, you can specify which elements of an OpenAPI description you’re implementing, simplifying the generated code and avoiding over-complicating your application. Like.NET’s minimal APIs, Kiota is a tool for simplifying your development workflow, not adding more complications.

Microsoft makes it easy to get started with Kiota. As it’s designed to work with many different languages and toolchains, there is a mix of official and unofficial ways to install and use it. If the methods listed don’t work for you, it’s a.NET application and the source code is on GitHub, so you can compile it yourself.

Using Kiota in your development toolchain

The first (and probably most likely) option is to simply download the binaries. Versions are available for Linux, macOS, and Windows. The documentation doesn’t mention Arm builds for Linux or Windows, but you can download a Linux Arm build from GitHub. Windows Arm users will need to download an x64 build and use Windows’ Prism emulator.

An alternative is to use a prebuilt Docker image. Microsoft provides some sample command line calls to build client libraries from local OpenAPI files and from online-hosted descriptions. If you’re using them from Windows, it’s a good idea to have Docker in WSL2 already installed and run the container inside your Linux environment, exporting the output to your choice of development environments.

If you are using a recent build of the.NET SDK, you can add Kiota to your toolchain from the.NET CLI. Again, there are versions for most common.NET development platforms, and you need the right runtime identifier to download the right version. For example, if you’re using a modern Apple Silicon Mac as a.NET development platform, use the osx-arm64 identifier to install the correct version.

You can automate the process of building client code by using Kiota from a GitHub Action. Start by defining the steps associated with checking out code, using a Microsoft-provided Kiota build to update clients when you check out code and working with a local branch. This ensures you’re always working against the most up-to-date version of the APIs your code is consuming.

There are community-built alternatives, using services like the asdf tool-version manager or the Homebrew macOS package manager. These tools use their own repositories, but if they’re your choice of toolchain package management, you can quickly add Kiota to an install script so you or your team can quickly refresh and update development devices.

Users of Visual Studio Code can take advantage of a preview extension that plugs Kiota directly into your editor. It’s not the same tool used by Visual Studio’s REST API Client Code Generator, which will install Kiota when needed, but it means that both of Microsoft’s main development tools can take advantage of its capabilities.

Working with Kiota-managed APIs

Using Kiota is relatively straightforward. If you’re using.NET, start by installing the Kiota command-line tool and ensure your project has the right settings for both the target framework and the language version. Modern.NET applications need to be.NET 6 or later (though you can use older versions with the right versions of.NET Standard). Languages have a similar requirement, with C# needing to be Version 7.3 or later.

Your code will need to include Kiota’s dependencies, which can be installed using its bundle. Microsoft details the required abstractions and packages for the supported languages, serialization options, and HTTP implementations. If you are using an authenticated API, you need to include support for various identity management tools. Using the bundles simplifies things considerably, though there are languages where you need to add dependency support as needed, such as Python and PHP.

You can now generate an API client from OpenAPI YAML. This can be a local file (most likely if you’re authoring your own OpenAPI descriptions) or a URL for public APIs. Client classes are generated using the command-line tool, defining the target language, the name of the client class, its namespace, the location of the OpenAPI YAML, and, finally, the output directory. You can use other options to tune the output, for example, reducing size by only building to the latest version of Kiota or reducing backwards compatibility.

Kiota builds the code needed to work with your API, and you can start to include it in your application. You will need to import the generated namespace, authorize the connection, and create a client object based on the class generated by Kiota. It’s all quite simple really, with calls to the API encapsulated in methods in the Kiota-generated class, with support for standard HTTP actions so you can get and post data from the API.

Choose your language

If you’re using another language, such as Python, the process is similar. With Python, however, there is no bundle of prerequisites and dependencies, so you need to use pip to install the appropriate Kiota libraries. The process of building and using a Kiota client is much the same as for.NET, importing classes as necessary and using them asynchronously.

The Kiota experience stays the same for each supported language: First, load dependencies into your project, build the client from an OpenAPI definition, and then import and use the generated client classes. Once you’ve defined the imports you’re using, you can refresh the client without affecting your application code—unless there’s an updated version of the API you’re calling.

So why use Kiota? The promise of OpenAPI was always that a common API description language would allow developers to automate the process of building clients. Kiota certainly delivers here, with a language-agnostic architecture that works with most common development toolchains. By delivering a standard set of classes, it keeps the learning curve to a minimum: You know what the output will be and how to use it in your code.

There are uses beyond the coding workflow. Kiota can quickly build tests for service-oriented architectures, dropping into a CI/CD pipeline to ensure services build correctly and are fit for use. Similarly, it can be used as part of a low-code environment, building and validating connectors ready for use in workflows.

That last option fits in well with agentic AI. Instead of generating new API calls every time a service runs in an AI query, Kiota clients could serve as the API equivalent of a semantic memory, capturing the API structure and leaving a client library ready for use by the AI in future operations. Giving agents an API memory should reduce risk and help manage and secure calls to services, keeping results consistent.