Enhance return types to Include HTTP response details

[jake-carpenter]

Is your feature request related to a problem? Please describe the problem.

One of the major shortcomings in many code generation tools is the assumption that HTTP calls are successful, otherwise throwing an error/exception. It is well-established best practice that try/catch blocks should not be used for flow control; instead, potential failures should be treated as conditions. Cleanly handling this becomes difficult when generated HTTP clients abstract away the details of an HTTP response needed for proper flow control.

The most common need to catch thrown errors/exceptions from generated code occurs with 400-level status codes. Some examples include:

• HTTP 401 indicates that reauthentication is required.
• HTTP 403 signals that a previously authorized user is no longer so, necessitating application action.
• HTTP 404 suggests that a new resource at the URI must be created to ensure a good user experience.

Currently, our only option to handle these non-exceptional cases is to catch the error/exception.

Client library/SDK language

None

Describe the solution you'd like

I would like to see an option to "wrap" or "augment" return types from generated clients to include useful HTTP response information such as:

• HTTP status code
• HTTP headers collection
• Any error information included in the HTTP content, as defined by the specification (if applicable)

In C#, where my primary concern lies, a common pattern is to wrap the success type with this additional information. However, other supported languages could use Either/Option/Maybe monads in their idiomatic ways.

It's important to consider that data streams passing between abstractions should be handled carefully. I am not requesting that all data from the HTTP request be included in every case.

Additional context

No response

[andrueastman]

Thanks for raising this @jake-carpenter

At the moment it is possible to implement the IResponseHandler interface.
https://github.com/microsoft/kiota-abstractions-dotnet/blob/d608605b9ec506a65cea2c90090a1d990fce6df9/src/IResponseHandler.cs#L15

With this, you can probably change the response handling to not throw on various Http status code and return a value as you wish.

The example below shows how one can use it to get the raw HttpResponseMessage and then manipulate as you wish without error throwing at 400/500 codes using the NativeResponseHandler.

var nativeResponseHandler = new NativeResponseHandler();
await graphClient.Me.GetAsync(requestConfiguration => requestConfiguration.Options.Add(new ResponseHandlerOption(){ ResponseHandler = nativeResponseHandler }));

var responseMessage = nativeResponseHandler.Value as HttpResponseMessage;

Any chance this extensibility point works out for you?

[jake-carpenter]

@andrueastman Thank you for bringing that to my attention. It's definitely nice to have that extension point as an option.

Ideally I would still like to see the generated code handle this itself to "make doing the right thing easy," but I'm glad to see it already has a flexible core.

[baywet]

To complement Andrew's answer, you can also use the HeadersInspectionOption to access the headers.
In additions, the thrown API exception has a response status code and response headers fields.
I want to be transparent with the fact that returning the deserialized response, or throwing an exception when a failure occurs are design choices as we believe it'll simplify the implementation for the vast majority of kiota clients users. Which is why it's unlikely to change any time soon unless we get overwhelming evidence it should.

[jake-carpenter]

@baywet As someone who has used various tools like this, I find this disappointing because my experience is that these scenarios significantly increase complexity.

• While I can access the status code in the exception, I still have to follow bad practices and catch to get it.
• When catching an exception, we lose all context of potential problem details as defined in RFC 7807 (based on the current implementation in C#).

Missing this feature leads to:

• Extra effort to work around the limitations with try/catch blocks or self-defined HTTP requests.
• Poorly defined API specifications to avoid issues with client-generating libraries.
• Low stickiness when a team encounters this use case.

Compared to a wrapper that provides the full context of the HTTP response, this approach is certainly not simpler.

I don't see it as a critical high-priority feature, but I hope it is reconsidered.

[baywet]

Thanks for the additional input.

For the error status codes, assuming the problem schema is present in the description. The kiota client will deserialize all problem information for you. And the exception will contain the headers + status code.
The code block you've provided is only the last resort (when nothing was registered for the status code).

As for accessing the successful response headers/status code/raw body, this is something we're evaluating the design of in #4698

[microsoft-github-policy-service]

This issue has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 4 days. It will be closed if no further activity occurs within 3 days of this comment.