You can create an instance of a WebClient by executing WebClient.create() which will have default settings and without a base uri set.

To change the default settings and register additional services, you can use simple builder that allows you to customize the client behavior.

WebClient client = WebClient.builder()
        .baseUri("http://localhost")
        .build();

WebClient offers a set of request methods that are used to specify the type of action to be performed on a given resource. Below are some examples of request methods:

• get()

• post()

• put()

• method(Method method)

Check out HttpClient API to learn more about request methods. These methods will create a new instance of HttpClientRequest which can then be configured to add optional settings that will customize the behavior of the request.

Configuration can be set for every request type before it is sent.

client.get()
        .uri("http://example.com") 
        .path("/path") 
        .queryParam("query", "parameter") 
        .fragment("someFragment") 
        .headers(headers -> headers.accept(MediaTypes.APPLICATION_JSON)); 

• Overrides baseUri from WebClient
• Adds path to the uri
• Adds query parameter to the request
• Adds fragment to the request
• Adds header to the request

For more information about these optional parameters, check out ClientRequestBase API, which is a parent class of HttpClientRequest.

HttpClientRequest class also provides specific header methods that help the user to set a particular header. Some examples of these are:

• contentType (MediaType contentType)

• accept (MediaType…​ mediaTypes)

For more information about these methods, check out ClientRequest API, which is a parent class of HttpClientRequest.

Once the request setup is completed, the following methods can be used to send it:

• HttpClientResponse request()

• <E> ClientResponseTyped<E> request(Class<E> type)

• <E> E requestEntity(Class<E> type)

• HttpClientResponse submit(Object entity)

• <T> ClientResponseTyped<T> submit(Object entity, Class<T> requestedType)

• HttpClientResponse outputStream(OutputStreamHandler outputStreamConsumer)

• <T> ClientResponseTyped<T> outputStream(OutputStreamHandler outputStreamConsumer, Class<T> requestedType)

Each of the methods will provide a way to allow response to be retrieved in a particular response type. Refer to ClientRequest API for more details about these methods.

ClientResponseTyped<String> response = client.get()
        .path("/endpoint")
        .request(String.class);
String entityString = response.entity();

WebClient currently supports HTTP/1.1 and HTTP/2 protocols. Below are the rules on which specific protocol will be used:

• Using plain socket triggers WebClient to process a request using HTTP/1.1.

• When using TLS, the client will use ALPN (protocol negotiation) to use appropriate HTTP version (either 1.1, or 2). HTTP/2 has a higher weight, so it is chosen if supported by both sides.

• A specific protocol can be explicitly selected by calling HttpClientRequest#protocolId(String).

String result = client.get()
        .protocolId("http/1.1")
        .requestEntity(String.class);

• If HTTP/2 is used, an upgrade attempt will be performed. If it fails, the client falls-back to HTTP/1.1.

• The parameter prior-knowledge can be defined using HTTP/2 protocol configuration. Please refer to on how to customize HTTP/2. In such a case, prior-knowledge will be used and fail if it is unable to switch to HTTP/2.

Webclient supports the following built-in Helidon Media Support libraries:

1. JSON Processing (JSON-P)
2. JSON Binding (JSON-B)
3. Jackson

They can be activated by adding their corresponding libraries into the classpath. This can simply be done by adding their corresponding dependencies.

<dependency>
    <groupId>io.helidon.http.media</groupId>
    <artifactId>helidon-http-media-jsonp</artifactId>
</dependency>

<dependency>
    <groupId>io.helidon.http.media</groupId>
    <artifactId>helidon-http-media-jsonb</artifactId>
</dependency>

<dependency>
    <groupId>io.helidon.http.media</groupId>
    <artifactId>helidon-http-media-jackson</artifactId>
</dependency>

Users can also create their own Custom Media Support library and make them work by following either of the approaches:

• Create a Provider of the Custom Media Support and expose it via Service Loader followed by adding the Media Support library to the classpath.

• Explicitly register the Custom Media Support from WebClient.

WebClient.builder()
        .mediaContext(it -> it
                .addMediaSupport(CustomMediaSupport.create())) 
        .build();

• Register CustomMedia support from the WebClient.

Webclient provides three DNS resolver implementations out of the box:

• Java DNS resolution is the default.

• First DNS resolution uses the first IP address from a DNS lookup. To enable this option, add below dependency:

<dependency>
    <groupId>io.helidon.webclient.dns.resolver</groupId>
    <artifactId>helidon-webclient-dns-resolver-first</artifactId>
</dependency>

• Round-Robin DNS resolution cycles through IP addresses from a DNS lookup. To enable this option, add this dependency:

<dependency>
    <groupId>io.helidon.webclient.dns.resolver</groupId>
    <artifactId>helidon-webclient-dns-resolver-round-robin</artifactId>
</dependency>

Protocol specific configuration can be set using the protocol-configs parameter. Webclient currently supports HTTP/1.1. and HTTP/2. Below are the options for each of the protocol type:

• HTTP/1.1

Configuration options

Configuration options

client:
  connect-timeout-millis: 2000
  read-timeout-millis: 2000
  follow-redirects: true 
  max-redirects: 5
  cookie-manager: 
    automatic-store-enabled: true
    default-cookies:
      flavor3: strawberry
      flavor4: raspberry
  default-headers: 
    Accept: '"application/json", "text/plain"'
  services: 
    metrics:
      - methods: ["PUT", "POST", "DELETE"]
        type: METER
        name-format: "client.meter.overall"
      - type: TIMER
        # meter per method
        name-format: "client.meter.%1$s"
      - methods: ["GET"]
        type: COUNTER
        errors: false
        name-format: "client.counter.%1$s.success"
        description: "Counter of successful GET requests"
      - methods: ["PUT", "POST", "DELETE"]
        type: COUNTER
        success: false
        name-format: "wc.counter.%1$s.error"
        description: "Counter of failed PUT, POST and DELETE requests"
    tracing:
  protocol-configs: 
    http_1_1:
      max-header-size: 20000
      validate-request-headers: true
    h2:
      prior-knowledge: true
  proxy: 
    host: "hostName"
    port: 80
    no-proxy: ["localhost:8080", ".helidon.io", "192.168.1.1"]
  tls: 
    trust:
      keystore:
        passphrase: "password"
        trust-store: true
        resource:
          resource-path: "client.p12"

• Client functional settings
• Cookie management
• Default client headers
• Client service configuration
• Protocol configuration
• Proxy configuration
• TLS configuration

Configure Proxy setup either programmatically or via the Helidon configuration framework.

Configuring Proxy in your code

Proxy proxy = Proxy.builder()
        .type(Proxy.ProxyType.HTTP)
        .host(PROXY_HOST)
        .port(PROXY_PORT)
        .build();
WebClient.builder()
        .proxy(proxy)
        .build();

Proxy proxy = Proxy.create(); 
HttpClientResponse response = client.get("/proxiedresource")
        .proxy(proxy) 
        .request();

Configuring Proxy in the config file

client:
  proxy:
    host: "hostName"
    port: 80
    no-proxy: ["localhost:8080", ".helidon.io", "192.168.1.1"]

Config config = Config.create(); 
WebClient.builder()
        .config(config.get("client")) 
        .build();

Configure TLS either programmatically or by the Helidon configuration framework.

Configuring TLS in your code

WebClient.builder()
        .tls(it -> it.trust(t -> t
                .keystore(k -> k.passphrase("password")
                        .trustStore(true)
                        .keystore(r -> r.resourcePath("client.p12")))))
        .build();

Configuring TLS in the config file

client:
  tls:
    trust:
      keystore:
        passphrase: "password"
        trust-store: true
        resource:
          resource-path: "client.p12"

Config config = Config.create(); 
WebClient.builder()
        .config(config.get("client")) 
        .build();

WebClient currently supports several built-in services, namely

• discovery

• metrics

• tracing

• telemetry (following OpenTelemetry semantic conventions)

  • metrics

  • tracing

• security.

Enabling the service

Adding a service in your code

WebClientService clientService = WebClientMetrics.counter()
        .methods(Method.GET)
        .nameFormat("example.metric.%1$s.%2$s")
        .build(); 

WebClient.builder()
        .addService(clientService) 
        .build();

Adding service in the config file

webclient:
  services:
    metrics:
      - type: METER
        name-format: "client.meter.overall"
      - type: TIMER
        # meter per method
        name-format: "client.meter.%1$s"
      - methods: ["PUT", "POST", "DELETE"]
        type: COUNTER
        success: false
        name-format: "wc.counter.%1$s.error"
        description: "Counter of failed PUT, POST and DELETE requests"
    tracing:

Config config = Config.create(); 
WebClient.builder()
        .config(config.get("client")) 
        .build();

Individual protocols can be customized using the protocol-config parameter.

Setting up protocol configuration in your code

WebClient.builder()
        .addProtocolConfig(Http1ClientProtocolConfig.builder()
                                   .defaultKeepAlive(false)
                                   .validateRequestHeaders(true)
                                   .validateResponseHeaders(false)
                                   .build())
        .build();

Setting up protocol configuration in the config file

webclient:
  protocol-configs:
    http_1_1:
      max-header-size: 20000
      validate-request-headers: true
    h2:
      prior-knowledge: true

Config config = Config.create(); 
WebClient.builder()
        .config(config.get("client")) 
        .build();

The telemetry webclient services provide metrics and tracing spans which follow the OpenTelemetry semantic conventions for clients. These are separate from the services.metrics and services.tracing services described elsewhere on this page.

To enable the telemetry webclient services, take the following two steps:

• Add the appropriate dependency.

• Add configuration or code to activate the telemetry services.

To set up metrics and tracing, add the following single dependency to your project:

<dependency>
    <groupId>io.helidon.webclient</groupId>
    <artifactId>helidon-webclient-telemetry</artifactId>
    <scope>runtime</scope>
</dependency>

To transmit the metrics semantic conventions to a backend, add a dependency on an OpenTelemetry exporter and in the telemetry configuration set up an exporter under signals.metrics.

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
    <scope>runtime</scope>
</dependency>

telemetry:
  service: my-app
  signals:
    metrics:
      exporters:
        type: otlp

To activate webclient telemetry collection using configuration, add the telemetry config section under client.services and, below it, add metrics, tracing, or both.

client:
  services:
    telemetry:
      metrics:
      tracing:

The metrics and tracing subsections have no explicit settings.

Alternatively, trigger webclient telemetry collection by modifying your client code to add one or more webclient telemetry services to the webclient builder. This example shows adding only telemetry metrics.

WebClient.builder()
        .addService(WebClientTelemetryMetrics.create())
        .build();

See the manifest for all available types.