Tailored SDK experiences via Kiota now generally available
Rabeb Othmani
Sébastien Levert
We’re happy to announce Kiota, our code generator for HTTP APIs described by OpenAPI, is available to all developers who want to focus on calling APIs in a consistent, robust and reliable way, without having to worry about the messy details of constructing HTTP requests. It is an open-source project, built on GitHub.
This release delivers a set of improvements as stated in the release notes. If you want to learn more about Kiota, read our full documentation.
What is Kiota?
Kiota is a command line tool for generating an API client to call any OpenAPI described API you are interested in. Kiota helps eliminate the need to take a dependency on a different API client for every API that you need to call, as well as limiting the generation to the exact API surface area you’re interested in, thanks to a filtering capability. Kiota API clients provide a strongly typed experience with features you’d expect from a high-quality API client (simple, reliable, secure and scalable), but without having to learn a new library for every HTTP API. It also provides embedded support for retry handling, secure redirects, transparent authentication and automatic payload compression.
Installation options
We have options to install Kiota. The easiest way would be to use our dotnet tool and install it globally on your environment. It’s as simple as running a single command and you will be able to generate client libraries in no time!
If you want to discover other ways to install Kiota (e.g., web, docker, build, etc.), review the getting started guide.
Using the tool
The first thing you will want to do with Kiota is search for APIs. To achieve this, using the Kiota search command will help identify and choose the right API for your business scenario.
Once you have identified the API to use, use that location with the parameter –openapi to visualize the API structure with the Kiota show command. This will give you confidence in the surface area that you want to generate for your client library. You can specify which paths you want to include by using the include glob pattern –include-path.
You are now only a command away to be able to leverage a rich client library experience. To generate your client library, use the kiota generate command.
Using a Kiota generated client
You can now use the Kiota generated client in your application using standardized API patterns.
Try out the new version today!
We’re excited about this release and can’t wait for you to try it out. We look forward to hearing from you about your experience with the tool and how we can continue to make Kiota even better.
Resources
- Learn more about Kiota
- Follow us on @Microsoft365Dev)/Twitter to stay up to date on news and announcements.
- Visit our Microsoft Graph Dev Center | APIs and app development for more resources.
Happy coding!
Rabeb Othmani Senior Product Manager
Light
Dark
2 comments
I said it on the related blog post about using Kiota and I’ll say it here, Kiota is an interesting experiment but honestly I cannot imagine anyone using it directly outside perhaps MS with the Graph API. As a OpenAPI client generator it pushes too much of the OpenAPI stuff up to clients such that using it directly in your code would be a bad idea. For example `client.findUser` is far more readable than `client.users.postasync`. That is sort of the whole purpose of operationIds in my opinion. You’re basically exposing the HTTP protocol to callers instead of wrapping them cleanly. If you don’t have an existing OpenAPI client generator like AutoRest or something then I can see a benefit but my view is that nobody is going to use a Kiota client directly.
Instead we’re going to wrap the client in a service layer that exposes the functionality we want using “friendly/descriptive” names and wraps the Kiota client. I see that you removed the version information from the client API but that is just one step to me. As a user of an API I don’t really care that this resource is a POST and that is a GET. I just want to “search for a user”, as an example. Kiota just exposes too much of the HTTP protocol. I could see people using Kiota to generate the client and then wrapping it in a service but at that point why take an OpenAPI spec and generate a Kiota client that wraps the HttpClient rather than just calling the client directly?
Kiota is also not currently very extensible and doesn’t handle some common cases in my opinion. So using the client directly also requires you to respond to some common situations. For example I think the request builder concept is a great idea but doing something like `client.Users[10].Projects.GetAsync` doesn’t handle the case of there being no user 10. So you have to wrap this code in a try-catch AND check the exception status code to see if the user exists or not. Most APIs I see return a 404 if the user is missing but Kiota sees it as an error and wastes the time building an exception for it. Since we may do this in many places an app would have the service wrapper handle this instead. Again, if we are going to be writing a wrapper around Kiota clients then why waste the time instead of just wrapping the HttpClient directly?
I do like how Kiota abstracts out HTTP and therefore makes it more testable. This appears to be lessons learned from the Azure SDK development process and I really agree with it. But I don’t think there is enough there to warrant exposing all the HTTP-specifics to an app and wrapping a wrapper around HttpClient seems like 1 step too many. I’d really like to see Kiota handle more common cases (like 404s) directly, generate friendlier clients for apps to consume (so we don’t need service wrappers) and be extensible for handling special cases.
Nice. Will definitely give it a try. How does it compare with AutoRest (also by Microsoft), NSWag and OpenAPI Generator?
Amazon also comes up with something called Smithy but I don’t like it.