Hi. I’m Luis Mañez, Atlas Chief Architect, and in this article, I am going to tell you about a new tool created by Microsoft, called Kiota. Kiota allows you to create a client for any API described using OpenApi.
As you may know, we develop a Digital Workplace solution called Atlas (find out more here: Atlas Digital Workplace for Microsoft Office 365 + Teams | ClearPeople). As part of our solution, we deploy an API that adds some cool provisioning features, and some other magic (which of course I cannot share or else... 😊).
It wasn’t that long ago that our first customer asked: “Could we call Atlas API from our custom solutions?” The answer was, obviously, yes, but that then sparked the “how” question.
What we did was to create some samples in a private repository and share them with our customers. That worked, but we wanted to offer a better solution, giving more freedom to our customers. So we added a backlog item to create a proper Atlas SDK. Our next challenge though was, what languages should we support? Would a C# SDK be enough? What about TypeScript?
Luckily, a year ago, Microsoft presented a very beta version of a tool called Kiota. Kiota allows you to create a client for any API described using OpenAPI. In Microsoft’s words:
“Kiota is a command line tool for generating an API client to call any OpenAPI described API you are interested in. The goal is to eliminate the need to take a dependency on a different API SDK for every API that you need to call. Kiota API clients provide a strongly typed experience with all the features you expect from a high-quality API SDK, but without having to learn a new library for every HTTP API.”
We quickly saw the light; we could provide an Atlas SDK in just minutes, supporting almost any well-known language, and even selecting what Atlas API resources we want to include in the SDK (only interested in provisioning? Good. You just want to search workspace capabilities? Fine).
Note: A year later, the tool is still in public preview, but so far so good. We advise our customers on any scenario they present, and we support them in resolving any issues. They understand that we’re still in preview too.
I am not going to go into detail, but in case this is new to you, OpenAPI is a standard for describing APIs. Some time ago, some of the most API-experienced people gathered and created a standard to describe APIs. In a nutshell, you create a json or yaml file, with a specific format, describing your API: Title, Version, Endpoints, HTTP Verbs for those endpoint, Response codes and types of those endpoints, etc. The image below provides a small sample:
Usually no one creates that file from scratch because there are tools to generate it directly from your API source code. You probably use Swagger library for asp.net. Swagger not only provides a UI for testing your API, but it also provides an OpenAPI description file (the UI is generated from that file).
And hey, look at this image from the OpenAPI website home page! There’s the one and only Yina Arenas, queen of the Microsoft Graph API!
As said before, Kiota is just a command-line tool. You can install it like a dotnet tool, inside a docker container or you can download the source code and compile it. As a dotnet guy, I installed it as a dotnet tool. Once installed, you just need to run the following command:
This command will generate the API client with the different files in the output specified folder.
This is the code auto-generated by Kiota from a small API that interacts with MS Teams Graph API:
Now let´s see how we can authenticate our Kiota client code when the API it's consuming is secured by Azure AD.
To help with that process, Kiota provides a class called “AzureIdentityAuthenticationProvider”. That class is integrated with the Azure.Identity SDK and it requires a “TokenCredential” class. You can get that “TokenCredential” using different approaches, depending on the different flows provided by Azure AD and your scenario. In this sample we’re going to use the interactive flow, that is the one with a browser pop-up that prompts you to enter your username and password. Here’s the full code:
That’s all for now. Kiota is a great tool for generating an SDK for your API and we’ll continue using it in our Atlas solution.
In my next blog, we’ll see how we can use a Kiota client inside a SharePoint framework solution and how we can create our own Authentication provider, reusing some of the magic provided by the SharePoint framework when dealing with Azure AD secured APIs. Plus how to integrate it into the Kiota pipeline.
Welcome to Kiota - kiota (microsoft.github.io)
microsoft/kiota: OpenAPI based HTTP Client code generator (github.com)
Using Kiota to generate a TypeScript SDK for Microsoft Graph - YouTube
Using a Kiota client for your API in a SharePoint framework solution