kiota: [.NET]: How do I react to unexpected status codes? Or, how do I read the response itself?

yes, this is the thinking behind kiota. Instead of having to write convoluted code to handle tangent scenarios (after all, the goal is to have the call succeed) in every and each application that depends on the API, let’s fix the API description so it benefits everyone, at every stage. And if you think about it, it’s a fault of the API owners to have implemented another response code, but not documented it in their descriptions.

Now, we acknowledge the loop to get the description fixed can be shorter or longer depending on the scenario:

• When you own the API you’re generating a client for: minutes.
• When your organization owns the API you’re generating a client for: hours.
• When you rely on another organization: variable, could be days, could be months.

We don’t have a clear solution for the 3rd case, hopefully API producers care about their APIs and the associated description because it is somehow tied to revenue. But a workaround, after reaching out and not getting satisfactory/timely resolution, could be to copy the description locally, make a couple of edits, commit it to your repo (so you can repeat the generation) and using that instead of the vendor provided description.

Yes, please create the issue for the missing docs topics, you wouldn’t know how much it helps to have a customer complaining constructively sometimes 😃

Hi everyone 👋, Thanks for your interest in kiota, for reaching out and for the great feedback on this thread. I’ll try to reply to every point without forgetting anything.

Documentation

We know we have a painful gap in our public documentation today, this is mostly due to a staffing issue for technical writers we’ve been trying to resolve for months on end now. In the meantime we’re trying to collect all those gaps, so don’t hesitate to create issues that are focused on one point at a time in the dedicated repository

General design

The general design of kiota clients is the application developers should not have to “deal with HTTP” in most cases anymore. This assumes the API description has enough information. The errors classes responses (4XX, 5XX) will be thrown as exceptions, exceptions generated from the API description.

Errors and factories

The exception thrown from the client in case of an error class response depend on what’s described by the OpenAPI description. The logic follows this order, (let’s assume we received a 503 from the service):

1. if a 503 response is documented, use the generated type for that.
2. else if a 5XX response is documented, use the generated type for that.
3. else throw the generic API exception you’ve seen earlier.
4. for cases 1 & 2, if the payload cannot be parsed into the generated type, throw the generic API exception as well.

In any case, all generated exceptions derive from API exception, and that has fields for the return status code as well as the responses headers. We didn’t include the response body mostly out of a performance concern.

If you want to include more errors/factories, simply edit the description to document additional response codes/classes.

Cross cutting concerns at the HTTP level

One thing this thread hasn’t mentioned yet, is the middleware stack. For concerns like “save any request/response to a third party service for audit purposes”, you can implement a middleware handler, and add it to the stack, see the retry handler as an example and let me know if you have further questions on this aspect.

Tracing

The clients implement Open Telemetry tracing, so if you want more details over what’s going on, you can turn on the diagnostics sources for Microsoft.Kiota.Http.HttpClientLibrary, Microsoft.Kiota.Abstractions and Microsoft.Kiota.Authentication.Azure (if you’re using this authentication provider).

Accessing the native request/response ad-hoc

Again, the design philosophy is that you don’t need to access the native http requests/responses, and improve the OpenAPI description instead as it’ll benefit not only the client you’re generating, but also the other clients/tools in your toolchain. Should you still need to do so, there are multiple ways.

IReponseHandler

You’ve already mentioned this one, you can implement that interface and pass that to a request through the response handler option. When you use that option, kiota will expect you to handle everything from the response to throwing an exception/returning the deserialized value in the implementation. This is designed this way to avoid reading the response multiple times and creating performance bottlenecks.

var myHandlerOption = new ResponseHandlerOption {
   Handler = myHandlerInstance,
};
var result = await client.Foo.Bar.GetAsync(x -> x.Options.Add(myHandlerOption));

The NativeResponseWrapper is a remnant of an earlier design, it only exists in dotnet, and we should consider marking it obsolete IMHO.

HeadersInspectionHandlerOption

this option allows you to observe the request and response headers only. Here is how you use it. We didn’t copy the request/response body to avoid performance issues here as well.

var observeOptions = new HeadersInspectionHandlerOption {
   InspectRequestHeaders = true,
   InspectResponseHeaders = true,
};
var result = await client.Foo.Bar.GetAsync(x -> x.Options.Add(observeOptions));
// read the headers and do something

Response turnaround

For information, most of (Microsoft part of) the team is based either in Kenya, East or West coasts. Expect most replies to thread to happen during work days on those time zones.

Hopefully I addressed all questions/concerns, don’t hesitate to follow up here.

Hey everyone, Thanks for bringing this up. We forgot to update one of the files, the page was effectively in the breadcrumb, but not in the table of contents. Just put together this to address the issue. https://github.com/MicrosoftDocs/openapi-docs/pull/41

As noted, I’ve added some docs to the Learn website so we can help others who had the same issues.

currently here: https://learn.microsoft.com/en-gb/openapi/kiota/middleware

Just for reference and not directly related to Kiota core package but this answers the question about getting access to the Request.

NOTE: As above, if the Swagger response document is correct you will get the response from Kiota - Still think the Pure response should be added to the default error handler

Implementing Middleware

Implement middleware to access the pure request.

Middleware class

Create your middleware class and add your business logic

public class SaveRequestHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        string jsonContent = await request.Content.ReadAsStringAsync();
        Console.WriteLine($"Request: {jsonContent}");

        return await base.SendAsync(request, cancellationToken);
    }
}

Register Middleware

Create a Middleware delegate array however, make sure to use the existing Middleware already implemented within Kiota.HttpClient. This includes Retry, redirect handling and more.

var delegates = KiotaClientFactory.CreateDefaultHandlers();
delegates.Add(new SaveRequestHandler());

Next we create a Delegate chain so middleware is registered in the right order

var handler =
    KiotaClientFactory.ChainHandlersCollectionAndGetFirstLink(
        KiotaClientFactory.GetDefaultHttpMessageHandler(),
        delegates.ToArray());

Finally create the HttpClient and then the Adapter

var httpClient = new HttpClient(handler!);
var adapter = new HttpClientRequestAdapter(authProvider, httpClient:httpClient);
var client = new PostsClient(adapter);

I will spend some time cleaning this up and adding to the Docs - then PR

Thanx

Am I right in understanding then that the only thing I really should have to tweak in order to get what I want is the OpenApi schema itself? In retrospect that actually makes a lot of sense, but it didn’t really occur to me that it was something I - as a consumer of the API - was “allowed to do”.

yes I had that head-desk moment

@baywet thanx for the great response. Pointing me in the right direction for the middleware is great. I could see the comments in the code but couldn’t find out how to implement middleware. This is defo needed within the core Docs.

I am going to try an add a Middleware that records the request and response. I think I should be able to pull this off. Also a Kiota Middleware Repository may be a cools idea…

Also to finish, I realised from the Docs that the whole Microsoft.Kiota.Http.HttpClientLibrary can be replaced… So that also solves my problem; but I like Middleware idea better.

Thanx all!! My team really love this product BTW

After some rudimentary testing, simply fixing the OpenAPI schema seems to do the trick. It also feels a lot less hacky than anything else I can think of, which is perfect.

Sometimes you don’t really think about the obvious solutions and instead try find a way around the problem instead.

Looks like Kiota is back on the menu, boys!

I think I’ll give up on Kiota for now, and maybe return if/when we ever get a response on this issue. In the best case scenario I can simply revert back to the old state, but I’m guessing this issue won’t be fixed in the coming days, and I can’t spend any more time on this than I already have. Unfortunate, as the API interface Kiota generates (the fluent one) is a lot better than the mess that NSwag generates.

I just thought I might’ve overlooked something so I went out of bed to check on how it worked and there’s a fundamental flaw with the “solution” I found; An IResponseHandler takes over the entire response flow.

Yes, it gives you access to partially affect the error path… but you lose the happy path along the way.

The following is the response flow of the SendAsync method on HttpClientRequestAdapter(The other model-returning methods are, for all intents and purposes, identical to this). As you can see, specifying a responseHandler more-or-less bypasses the entire reason you used Kiota in the first place.

It skips that entire response handling flow and goes straight to your IResponseHandler implementation. I guess that is theoretically fine for a SendNoContentAsync - which is what I was testing with - but unless you recreate the entire happy path along the way - which obviously makes no sense - it’s still fundamentally flawed.

The following is the SendNoContentAsync on HttpClientRequestAdapter. As you can see, specifying a responseHandler doesn’t really affect the happy path - by virtue of it not really having one - but it still technically bypasses it in its entirety. The fact it didn’t really have a happy path to begin with is probably why I didn’t think about it before just now… And I was so happy with finally figuring something out 😭

This goes all the way back to the errorMappings. That seems to have the most potential here, but without any way of actually adding some of those - without manually editing the generated code - we’re not any closer than I was at this time yesterday.

I guess we could technically create a custom implementation of HttpClientRequestAdapter that “intercepts” all the calls and adds in our custom errorMappings, but that cannot possibly be what Microsoft intended when they designed this project.

OK, IMO this can’t be done with the current codebase…

In order to handle unique (real life) error responses we need to be able to override the “errorMapping” used within the requestBuilder. Changing this code is a bad idea, as this is generated.

I have been able to do a PoC by overriding the Error Mapper for 400 (very bad code, it’s just a PoC).

        public async Task<Type_3?> PostAsync(Type_2 body, Action<FullQuoteRequestBuilderPostRequestConfiguration>? requestConfiguration = default, CancellationToken cancellationToken = default) {
#nullable restore
#else
        public async Task<Type_3> PostAsync(Type_2 body, Action<FullQuoteRequestBuilderPostRequestConfiguration> requestConfiguration = default, CancellationToken cancellationToken = default) {
#endif
            _ = body ?? throw new ArgumentNullException(nameof(body));
            var requestInfo = ToPostRequestInformation(body, requestConfiguration);
            var errorMapping = new Dictionary<string, ParsableFactory<IParsable>> {
                {"400", ErrorResponse.CreateFromCusomDiscriminatorValue},
                {"401", ErrorResponse.CreateFromDiscriminatorValue},
                {"404", ErrorResponse.CreateFromDiscriminatorValue},
                {"405", ErrorResponse.CreateFromDiscriminatorValue},
                {"406", ErrorResponse.CreateFromDiscriminatorValue},
                {"415", ErrorResponse.CreateFromDiscriminatorValue},
                {"500", ErrorResponse.CreateFromDiscriminatorValue},
            };
            return await RequestAdapter.SendAsync<Type_3>(requestInfo, Type_3.CreateFromDiscriminatorValue, errorMapping, cancellationToken).ConfigureAwait(false);
        }

NOTE:

 {"400", ErrorResponse.CreateFromCusomDiscriminatorValue},

Then I created my own Error Response and handler based on the unique response from this API I am integrating with.

        /// <summary>
        /// Custom error response
        /// </summary>
        /// <param name="parseNode">The parse node to use to read the discriminator value and create the object</param>
        public static ErrorResponse CreateFromCustomDiscriminatorValue(IParseNode parseNode) {
            _ = parseNode ?? throw new ArgumentNullException(nameof(parseNode));
            var err = new ErrorResponse()
            {
                // messageez??? What the hell
                AdditionalData = new Dictionary<string, object>(new KeyValuePair<string, object>[] {
                    new KeyValuePair<string, object>("code", parseNode.GetChildNode("code").GetStringValue()),
                    new KeyValuePair<string, object>("message", parseNode.GetChildNode("messageez").GetStringValue())
                })
            };

            return err;
        }

What I propose is that we allow custom ErrorMappings to override/extend the defaults. Something like

var result = await client.FullQuote.PostAsync(body, x => {
            x.Headers.Add("Client-Id", "my-key"); 
            x.Headers.Add("Client-Secret", "Bob"); 
            .AddErrorMapping("400", CreateFromCustomDiscriminatorValue);
        });

NOTE: During my development the API is changing all the time (Multiple times per day). They are not a fixed “real boy” APIs but a system under high development. Therefore I am re-generating the Client all day long. This means I loose this code and have to reset. The Classes are not partial and I can’t get extension methods to work…

Does anyone have any ideas… am I missing something obvious?

OK after some diggin, technically it’s not the fault of this Package. The root cause comes from Microsoft.Kiota.Http.HttpClientLibrary.

This throws away the content/body of the response if it can’t be mapped to a errorMapping IParsable.

I am still digging to see if I can create a custom IParsable and attach it to the status code…

At the moment, the only way I can see the Response is to remove the Nuget package for Microsoft.Kiota.Http.HttpClientLibrary and use the code. Then put a breakpoint on jetbrains://rd/navigate/reference?project=KiotaExploded&path=kiota-http-dotnet/src/HttpClientRequestAdapter.cs:ThrowIfFailedResponse

NOTE: This is odd behaviour IMO. In some cases APIs return valuable information about validation, 500 errors stack traces and other goodies during development. This lib assumes a perfect payload and a perfect API… I’ve never see such a thing 😃