2 comments

Discussion is closed. Login to edit/delete existing comments.

• 

  Dan B March 20, 2023 0

  Collapse this comment Copy link

  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.

• 

  Michael Taylor March 16, 2023 1

  Collapse this comment Copy link

  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....

  Read more

  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.

  Read less