From 1d38f87282e872176911398f2ba620d1b7cfdc62 Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Thu, 30 Jul 2026 13:03:35 -0300 Subject: [PATCH 1/4] W-23622424-update-HTTP-page --- modules/ROOT/pages/HTTP-based-connectors.adoc | 146 +++++++++++++++++- .../pages/forward-compatibility-patterns.adoc | 1 + .../pages/forward-compatibility-setup.adoc | 1 + 3 files changed, 142 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/HTTP-based-connectors.adoc b/modules/ROOT/pages/HTTP-based-connectors.adoc index e82edd5b..6b14a81b 100644 --- a/modules/ROOT/pages/HTTP-based-connectors.adoc +++ b/modules/ROOT/pages/HTTP-based-connectors.adoc @@ -15,6 +15,136 @@ For example, the Amazon AWS connectors work by consuming an HTTP API that requir However, a client library that does nothing but wrap an HTTP client for convenience (like the Google clients) is not a valid exception to this rule. +=== Create the HTTP Client + +There are two APIs for creating a Mule `HttpClient`: + +* The `org.mule.sdk.api.http` API (recommended). Its entry point is `HttpService.client(Consumer)`. Because `mule-sdk-api` is bundled with your connector and isn't coupled to the Mule Runtime lifecycle, a connector can use this API to consume newer HTTP features without raising its Minimum Mule Version. Use this API for new connectors and when migrating an existing connector that needs newer HTTP capabilities. See xref:forward-compatibility.adoc[] for more about forward compatibility. +* The legacy `org.mule.runtime.http.api` API, whose `HttpClient` is created from an `HttpClientConfiguration` builder through `httpService.getClientFactory().create(...)`. This API remains fully supported and is a valid choice when your connector's Minimum Mule Version already permits it. See <>. + +==== Use the org.mule.sdk.api HTTP Client + +Inject the `org.mule.sdk.api.http.HttpService` and call `client(...)` with a callback that configures the client through an `HttpClientConfigurer`: + +[source,java,linenums] +---- +@Inject +private HttpService httpService; + +HttpClient client = httpService.client(configurer -> configurer + .setName("client-name") + // other setters... +); +---- + +The `HttpService.client(...)` method returns an `org.mule.sdk.api.http.client.HttpClient` and throws a `ClientCreationException` if the client can't be created. + +==== Configure the Client + +The `HttpClientConfigurer` passed to the callback exposes these methods. Each one returns the same configurer, so you can chain the calls: + +[%header,cols="1,3"] +|=== +| Method | Description + +| `setName(String)` +| Sets the name of the `HttpClient`. Base it on the name of the owning configuration (see <>). + +| `setTlsContextFactory(TlsContextFactory)` +| Required for HTTPS. Provides the TLS data used to establish secure connections. + +| `setMaxConnections(int)` +| Maximum number of outbound connections kept open at the same time. Unlimited by default. + +| `setUsePersistentConnections(boolean)` +| Whether connections are kept open after a request completes. `true` by default. + +| `setConnectionIdleTimeout(int)` +| Number of milliseconds a connection can remain idle before being closed. + +| `setResponseBufferSize(int)` +| Size, in bytes, of the buffer used to store the HTTP response. Defaults to 10 KB. + +| `setStreaming(boolean)` +| Whether the HTTP response is streamed, so processing continues as the body arrives. + +| `setDecompress(Boolean)` +| Whether responses are decompressed automatically. `false` by default. + +| `configProxy(Consumer)` +| Configures a proxy for the client. See <>. + +| `configHttp1(Consumer)` +| Enables, disables, and configures HTTP/1-specific parameters. + +| `configHttp2(Consumer)` +| Enables, disables, and configures HTTP/2-specific parameters. + +| `configClientSocketProperties(Consumer)` +| Configures TCP-specific properties, such as the socket connection timeout. +|=== + +For the complete reference, see the `HttpClientConfigurer` interface (package `org.mule.sdk.api.http.client`) in the `mule-sdk-api` javadoc. + +==== Send a Request + +The `HttpClient` implements `Startable` and `Stoppable`, so it *must* be started before use and stopped when you no longer need it. Build requests with `HttpService.requestBuilder()` and send them without blocking through `sendAsync(...)`, which returns a `CompletableFuture`: + +[source,java,linenums] +---- +client.start(); + +HttpRequest request = httpService.requestBuilder() + .method(GET) + .uri("https://api.example.com/resource") + .build(); + +CompletableFuture future = client.sendAsync(request, options -> options + .setResponseTimeout(5000) + .setFollowsRedirect(true)); + +// ... use the response, then stop the client during the stop() phase +client.stop(); +---- + +Because `sendAsync(...)` defers response body processing, handle the response on a different thread when you need the full body right away — for example, with `CompletableFuture.whenCompleteAsync(...)`. This avoids blocking the client's I/O threads. + +==== Migrate from the Legacy HTTP Client + +If your connector currently creates its client with the legacy `org.mule.runtime.http.api.client.HttpClient` and the `HttpClientConfiguration` builder, you can move to the configurer-based API as follows: + +* Replace the injected `org.mule.runtime.http.api.HttpService` with `org.mule.sdk.api.http.HttpService`. +* Replace `httpService.getClientFactory().create(new HttpClientConfiguration.Builder()...build())` with `httpService.client(configurer -> ...)`, mapping each builder setter to the equivalent configurer method (for example, `.setName(...)`). +* Update the imports of `HttpClient`, `HttpRequest`, `HttpResponse`, and related types to their `org.mule.sdk.api.http` counterparts. + +Note these points about this migration: + +* The new API delegates to the legacy one and *does not* deprecate it. +* The legacy API remains valid. You can keep using it when your connector's Minimum Mule Version already permits it. +* Moving to the new API is the recommended path when a connector wants access to newer HTTP features without raising its Minimum Mule Version. + +Because the new HTTP types come from `org.mule.sdk.api`, follow the guidance in xref:forward-compatibility-patterns.adoc[] when you need to call newer methods conditionally and provide fallback behavior for older runtimes. + +[[legacy-http-client]] +==== Use the Legacy org.mule.runtime.http.api HTTP Client + +The legacy API creates the `HttpClient` from an `HttpClientConfiguration` builder: + +[source,java,linenums] +---- +httpClient = httpService.getClientFactory() + .create(new HttpClientConfiguration.Builder() + .setName(configName) + .build()); +httpClient.start(); +---- + +This API is still fully supported. Use it when your connector's Minimum Mule Version already covers it and you don't need the newer HTTP features exposed by `org.mule.sdk.api.http`. + +=== Manage the Client in a Connection Provider + +Regardless of which API creates the `HttpClient`, the connector's `ConnectionProvider` is responsible for managing it according to these rules. + * Handle the HTTP Client Lifecycle + The ConnectionProvider that creates the HttpClient is responsible for managing its lifecycle. @@ -41,10 +171,15 @@ public class HttpConnectionProvider implements CachedConnectionProvider configurer + .setName(configName) + .setTlsContextFactory(tlsContext)); httpClient.start(); } @@ -60,6 +195,7 @@ public class HttpConnectionProvider implements CachedConnectionProvider configurer.setName(configName)); httpClient.start(); } @@ -105,6 +238,7 @@ The HttpService allows you to obtain the HttpClient associated with a separate < + All connectors in need of a HttpClient instance, *must* create and manage their own. + +[[provide-http-proxy-configuration]] * Provide HTTP Proxy Configuration + Connectors using HTTP Client instances must provide the ability to configure a diff --git a/modules/ROOT/pages/forward-compatibility-patterns.adoc b/modules/ROOT/pages/forward-compatibility-patterns.adoc index 1a891b21..1397abaf 100644 --- a/modules/ROOT/pages/forward-compatibility-patterns.adoc +++ b/modules/ROOT/pages/forward-compatibility-patterns.adoc @@ -139,3 +139,4 @@ If a feature behaves differently on earlier versions, document this for your use * xref:forward-compatibility-enforcement.adoc[] * xref:forward-compatibility-min-mule-version.adoc[] * xref:forward-compatibility.adoc[] +* xref:HTTP-based-connectors.adoc[HTTP-Based Connectors] for the forward-compatible `org.mule.sdk.api.http` client API diff --git a/modules/ROOT/pages/forward-compatibility-setup.adoc b/modules/ROOT/pages/forward-compatibility-setup.adoc index dd1d0ada..99381707 100644 --- a/modules/ROOT/pages/forward-compatibility-setup.adoc +++ b/modules/ROOT/pages/forward-compatibility-setup.adoc @@ -64,3 +64,4 @@ See xref:forward-compatibility-min-mule-version.adoc[] for details on how versio * xref:forward-compatibility.adoc[] * xref:forward-compatibility-min-mule-version.adoc[] * xref:getting-started.adoc[] +* xref:HTTP-based-connectors.adoc[HTTP-Based Connectors] for the forward-compatible `org.mule.sdk.api.http` client API From 260a56c64a8a7cd1416f116b0cf6de91e5005a22 Mon Sep 17 00:00:00 2001 From: Luana Dos Santos <84200607+luanamulesoft@users.noreply.github.com> Date: Thu, 30 Jul 2026 13:37:42 -0300 Subject: [PATCH 2/4] Apply suggestion from @luanamulesoft --- modules/ROOT/pages/HTTP-based-connectors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/HTTP-based-connectors.adoc b/modules/ROOT/pages/HTTP-based-connectors.adoc index 6b14a81b..17b6332b 100644 --- a/modules/ROOT/pages/HTTP-based-connectors.adoc +++ b/modules/ROOT/pages/HTTP-based-connectors.adoc @@ -107,7 +107,7 @@ CompletableFuture future = client.sendAsync(request, options -> op client.stop(); ---- -Because `sendAsync(...)` defers response body processing, handle the response on a different thread when you need the full body right away — for example, with `CompletableFuture.whenCompleteAsync(...)`. This avoids blocking the client's I/O threads. +Because `sendAsync(...)` defers response body processing, handle the response on a different thread when you need the full body right away. For example, with `CompletableFuture.whenCompleteAsync(...)`. This avoids blocking the client's I/O threads. ==== Migrate from the Legacy HTTP Client From ab0132b04f58e2ee9abf974fa32310954c2ddb48 Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Thu, 30 Jul 2026 13:43:51 -0300 Subject: [PATCH 3/4] fixed note format --- modules/ROOT/pages/HTTP-based-connectors.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/HTTP-based-connectors.adoc b/modules/ROOT/pages/HTTP-based-connectors.adoc index 17b6332b..730b8702 100644 --- a/modules/ROOT/pages/HTTP-based-connectors.adoc +++ b/modules/ROOT/pages/HTTP-based-connectors.adoc @@ -117,11 +117,14 @@ If your connector currently creates its client with the legacy `org.mule.runtime * Replace `httpService.getClientFactory().create(new HttpClientConfiguration.Builder()...build())` with `httpService.client(configurer -> ...)`, mapping each builder setter to the equivalent configurer method (for example, `.setName(...)`). * Update the imports of `HttpClient`, `HttpRequest`, `HttpResponse`, and related types to their `org.mule.sdk.api.http` counterparts. -Note these points about this migration: +[NOTE] +==== +Keep these points in mind during the migration: * The new API delegates to the legacy one and *does not* deprecate it. * The legacy API remains valid. You can keep using it when your connector's Minimum Mule Version already permits it. * Moving to the new API is the recommended path when a connector wants access to newer HTTP features without raising its Minimum Mule Version. +==== Because the new HTTP types come from `org.mule.sdk.api`, follow the guidance in xref:forward-compatibility-patterns.adoc[] when you need to call newer methods conditionally and provide fallback behavior for older runtimes. From d8105a52a1a496c335e76f45370657c78622b023 Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Thu, 30 Jul 2026 13:52:05 -0300 Subject: [PATCH 4/4] reduced note --- modules/ROOT/pages/HTTP-based-connectors.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/modules/ROOT/pages/HTTP-based-connectors.adoc b/modules/ROOT/pages/HTTP-based-connectors.adoc index 730b8702..817d6ea0 100644 --- a/modules/ROOT/pages/HTTP-based-connectors.adoc +++ b/modules/ROOT/pages/HTTP-based-connectors.adoc @@ -119,8 +119,6 @@ If your connector currently creates its client with the legacy `org.mule.runtime [NOTE] ==== -Keep these points in mind during the migration: - * The new API delegates to the legacy one and *does not* deprecate it. * The legacy API remains valid. You can keep using it when your connector's Minimum Mule Version already permits it. * Moving to the new API is the recommended path when a connector wants access to newer HTTP features without raising its Minimum Mule Version.