[API Proposal]: Add QUERY verb support to HttpClient

[MitchBodmer]

Background and motivation

With the new QUERY verb reaching the Proposed Standard maturity level, now might be the right time to add it to HttpClient.

API Proposal

These methods added to HttpClient:

namespace System.Net.Http
{
    public partial class HttpClient : HttpMessageInvoker
    {
        public Task<HttpResponseMessage> QueryAsync(string? requestUri, HttpContent? content);

        public Task<HttpResponseMessage> QueryAsync(Uri? requestUri, HttpContent? content);

        public Task<HttpResponseMessage> QueryAsync(string? requestUri, HttpContent? content, CancellationToken cancellationToken);

        public Task<HttpResponseMessage> QueryAsync(Uri? requestUri, HttpContent? content, CancellationToken cancellationToken)
    }
}

A new static HttpMethod member called Query:

public partial class HttpMethod
{
    public static HttpMethod Query { get; }
}

And finally, all the expected QueryAsJsonAsync overloads:

namespace System.Net.Http.Json
{
    public static class HttpClientJsonExtensions
    {
        public static Task<HttpResponseMessage> QueryAsJsonAsync<TValue>(this HttpClient client, string? requestUri, TValue value, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default);

        public static Task<HttpResponseMessage> QueryAsJsonAsync<TValue>(this HttpClient client, Uri? requestUri, TValue value, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default);

        public static Task<HttpResponseMessage> QueryAsJsonAsync<TValue>(this HttpClient client, string? requestUri, TValue value, CancellationToken cancellationToken);

        public static Task<HttpResponseMessage> QueryAsJsonAsync<TValue>(this HttpClient client, Uri? requestUri, TValue value, CancellationToken cancellationToken);

        public static Task<HttpResponseMessage> QueryAsJsonAsync<TValue>(this HttpClient client, string? requestUri, TValue value, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default);

        public static Task<HttpResponseMessage> QueryAsJsonAsync<TValue>(this HttpClient client, Uri? requestUri, TValue value, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default);
    }
}

API Usage

This is intended to be used in the same way the current verbs with a body are used.

HttpClient httpClient = new();

var response = await httpClient.QueryAsync("https://myuri.com/path", someHttpContent);

Alternative Designs

No response

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/ncl
See info in area-owners.md if you want to be subscribed.

[wfurt]

We should perhaps first update HttpMethod first https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpmethod?view=net-10.0

[huoyaoyuan]

Not all http methods are directly exposed with a helper method in HttpClient, for example OPTIONS and TRACE.

[MitchBodmer]

@huoyaoyuan my intuition is that QUERY fits the mold of "methods that are intended to be common ways for developers to explicitly interact with endpoints", which seems to be why some of these get helpers and some don't. In very broad terms, this method is supposed to replace all GETs with a body and idempotent POSTs, which seems to put it firmly into the class of methods that get helpers.

That's just my impression from looking at the API though. I'm happy to be corrected.

[MitchBodmer]

@wfurt Do you mean we should sequence the changes to be one after another:

1. Update HttpMethod with the new verb.
2. Update HttpClient and extensions.

Or did you just mean some other kind of updates on HttpMethod that I'm not thinking of?

I realized I kind of hid the line that says "A new static HttpMethod member called Query." between two code blocks.

[MihaZupan]

I realized I kind of hid the line that says "A new static HttpMethod member called Query." between two code blocks.

Yes, we just meant that the API proposal should explicitly include

public partial class HttpMethod
{
    public static HttpMethod Query { get; }
}

which seems uncontroversial even if we never ended up adding other helpers (not saying we wouldn't).

[MitchBodmer]

Cool thanks, @MihaZupan. I've updated the proposal.

I'd be more than willing to take a crack at this if this is something you're all willing to move forward with.

[MitchBodmer]

I know I'm getting a little ahead of myself here, but I had some time to throw together what I think this change would be in this branch. The JSON extensions are in this branch.

I'm assuming we would also have to update the docs here, here, and here.

Are there any other code changes this would require?