(non default) Request Headers

[JTeeuwissen]

Is your feature request related to a problem? Please describe.
Currently, whenever we want to modify the headers for a http request, we have to reset and then set the FhirClient.RequestHeaders. But these headers (HttpClient.DefaultRequestHeaders) are not mend for frequent manipulation and they are not thread-safe.

Describe the solution you'd like
I'd like each BaseFhirClient method to have an overload (or optional parameter, but this would be a breaking change) with a HttpRequestHeaders parameter. Which can be passed to
ToHttpRequestMessage where it can be used to add headers to the HttpRequestMessage

var message = new HttpRequestMessage(method, uri);
if (headers is not null)
{
    foreach (var httpRequestHeader in headers)
    {
        message.Headers.Add(httpRequestHeader.Key, httpRequestHeader.Value);
    }
}

Describe alternatives you've considered
Another option would be using http client middleware. But this doesn't play nice with scoping and doesn't allow for local values to be passed in the headers.

[ewoutkramer]

Passing a full HttpRequestMessage object as the parameter has a few complications worth noting:

1. Most properties would be silently ignored/overwritten. The SDK internally builds its own HttpRequestMessage — setting the URL, HTTP method, content body, Accept, If-Match/If-None-Match, return-prefer headers, etc. If the user passes a full HttpRequestMessage, only the custom headers could realistically be merged in; the URL, method, and content would be thrown away without any warning.

2. Ownership and disposal. HttpRequestMessage implements IDisposable, and HttpClient.SendAsync takes ownership of (and disposes) the request message after sending. This would make the caller responsible for creating something that the SDK destroys, and the object couldn't safely be reused afterward.

3. Single-use. A sent HttpRequestMessage cannot be resent. Callers who want to apply the same headers to multiple requests (e.g. in a loop) would have to recreate the object each time.

Given these constraints, we plan to use Action<HttpRequestHeaders> as the parameter type. The SDK creates the HttpRequestMessage internally and then passes its Headers collection to the callback, letting callers configure it freely:

await client.ReadAsync<Patient>("123",
    requestHeaders: h => h.Authorization = new AuthenticationHeaderValue("Bearer", token));

This avoids disposal ambiguity, is reusable across calls, and makes it clear that the SDK owns the full request while the caller controls only the headers.

[ewoutkramer]

Could we also invent something (like this callback that Claude mentions above) that we can add to the constructor, so it does not have to be added to each client method?