Document HttpClient configuration for IDownstreamApi

[Copilot]

IDownstreamApi uses IHttpClientFactory internally but lacked documentation on customizing the underlying HttpClient (timeouts, handlers, retry policies). Users discovered the pattern empirically: register a named HttpClient matching the downstream API service name.

Changes

Added section "Configuring the Underlying HttpClient" to docs/calling-downstream-apis/custom-apis.md:

• Explains IHttpClientFactory integration and named client mapping

• Basic configuration example:

  builder.Services.AddDownstreamApi("MyApi", options => 
  {
      options.BaseUrl = "https://api.example.com";
      options.Scopes = new[] { "api://my-api/read" };
  });
  
  // Configure the underlying HttpClient for "MyApi"
  builder.Services.AddHttpClient("MyApi", client =>
  {
      client.Timeout = TimeSpan.FromSeconds(30);
  });

• Advanced scenarios:

  • Custom message handlers (logging, telemetry)
  • Polly integration (retries, circuit breakers)
  • Debug timeouts via conditional compilation
  • Multiple API configurations

• Best practices (timeout values, handler composition, BaseUrl vs BaseAddress)

Updated docs/calling-downstream-apis/calling-downstream-apis-README.md:

• Added tip linking to HttpClient configuration guide after IDownstreamApi section

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Documentation] Missing documentation about how to configure the underlying HttpClient for IDownstreamApi</issue_title>
<issue_description>### Documentation related to component
This request for missing documentation is related with the usage of IDownstreamApi interface.

Please check all that apply

• typo
• documentation doesn't exist
• documentation needs clarification
• error(s) in the example
• needs an example

Description of the issue

I'm currently unable to find a documentation and a sample about how to customize the underlying HttpClient when using the IDownstreamApi interface to call a downstream api. This problem was originally discussed in #1740 and the suggested solution is to register an HttpClient with the very same name of the registered downstream api.

Since the original author of the issue confirmed that this solution works and there was no new guideline about this topic, my suggestion is to add an official statement and possibly an example to the documentation.
</issue_description>

Comments on the Issue (you are @copilot in this section)

@jmprieur Hello @tgourley. The Downstream APIs create the HTTP client using an IHttpClientFactory. therefore you can bring your own:

MyHttpClientFactory.cs

  // This is to avoid the HTTP connection to time out in the client while you are debugging
    // the web API. Setting a 30 mins timeout.
    internal class MyHttpClientFactory : IHttpClientFactory
    {
        public HttpClient CreateClient(string name)
        {
            var client = new HttpClient
            {
                // Adds a timeout to help debugging
                Timeout = TimeSpan.FromMinutes(30)
            };
            return client;
        }
    }

Program.cs:

// This is to avoid the HTTP connection to time out in the client while you are debugging
// the web API
services.AddSingleton<IHttpClientFactory, MyHttpClientFactory>();


Alternatively you could use the MicrosoftIdentityMessageHandler. this is documented here: https://github.com/AzureAD/microsoft-identity-web/blob/feature/doc-modernization/docs/calling-downstream-apis/custom-apis.md (making its way to learn.microsoft.com)</body></comment_new>
</comments>

• Fixes [Documentation] Missing documentation about how to configure the underlying HttpClient for IDownstreamApi #3258

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[jmprieur]

This should be in the downstream APIs article? Not this one? Or should it. What do you think @copilot ?

[Copilot]

I placed it in custom-apis.md because:

1. Detailed implementation guidance: The section provides in-depth examples (logging handlers, Polly integration, debugging scenarios) which align with the detailed nature of custom-apis.md
2. IDownstreamApi focus: The content is specifically about IDownstreamApi with custom APIs, which is the subject of this document
3. README is high-level: The calling-downstream-apis-README.md serves as an overview/decision guide with quick starts, while detailed "how-to" content belongs in the specific guides

However, I can move it to the main README if you prefer. The README's IDownstreamApi section currently has a quick start example, and this could be added as an advanced configuration subsection there. What would you prefer?