Configure the HTTP client

Stable — Production-ready with stable APIs and full test coverage.

Quarkus Flow supports calling external services over HTTP and OpenAPI. All HTTP and OpenAPI tasks share a common, tunable HTTP client layer powered by RESTEasy Reactive and Vert.x.

This guide shows how to:

  • Configure the default HTTP client.

  • Define named HTTP clients for specific external services.

  • Route specific workflows or tasks to a named client.

  • Configure static headers, logging, proxies, and TLS.

For retry and circuit breaker configurations, see Fault tolerance and resilience. For correlation headers, see Enable tracing.

Prerequisites

1. Understand the HTTP client model

All Flow HTTP and OpenAPI tasks use a jakarta.ws.rs.client.Client managed by Quarkus Flow.

At runtime, Quarkus Flow: * Builds a default client from quarkus.flow.http.client.. * Optionally builds *named clients from quarkus.flow.http.client.named.<name>.. * Resolves *which client to use for a given workflow or task using quarkus.flow.http.client.workflow.* routing. * Reuses and closes these clients automatically at the end of the application lifecycle.

2. Configure the default HTTP client

The default HTTP client is used when no routing is configured for a workflow or task.

# Basic timeouts (milliseconds)
quarkus.flow.http.client.connect-timeout=5000
quarkus.flow.http.client.read-timeout=10000

# HTTP connection pool and keep-alive
quarkus.flow.http.client.connection-pool-size=50
quarkus.flow.http.client.keep-alive-enabled=true
quarkus.flow.http.client.connection-ttl=60

# User agent
quarkus.flow.http.client.user-agent=quarkus-flow/1.0

3. Create named HTTP clients

You can declare as many named HTTP clients as you need, each with its own tuning.

# "secureA" – external API with strict timeouts and custom UA
quarkus.flow.http.client.named.secureA.connect-timeout=3000
quarkus.flow.http.client.named.secureA.read-timeout=8000
quarkus.flow.http.client.named.secureA.user-agent=MyCompanyBot/1.0

# "internal" – internal service with a larger pool and relaxed timeouts
quarkus.flow.http.client.named.internal.connect-timeout=1000
quarkus.flow.http.client.named.internal.read-timeout=20000
quarkus.flow.http.client.named.internal.connection-pool-size=100

4. Route workflows and tasks to clients

Routing is configured under the workflow section. Keys are composite identifiers that encode namespace, name, version, and optional task name.

Workflow-level routing (most common)

# Short key — route by workflow name only (99% use case)
quarkus.flow.http.client.workflow.order-flow.name=secureA

# Medium key — route by namespace and name
quarkus.flow.http.client.workflow."acme\:order-flow".name=secureA

# Full key — route by namespace, name and version
quarkus.flow.http.client.workflow."acme\:order-flow\:1.0.0".name=secureA

Task-level routing

# Short key — route a specific task by workflow name
quarkus.flow.http.client.workflow."order-flow.task.fetchCustomers".name=internal

# Medium key — with namespace
quarkus.flow.http.client.workflow."acme\:order-flow.task.fetchCustomers".name=internal

# Full key — with namespace and version
quarkus.flow.http.client.workflow."acme\:order-flow\:1.0.0.task.fetchCustomers".name=internal

Resolution order

When multiple routing rules match, the most specific one wins:

  1. Task-level full (most specific) — quarkus.flow.http.client.workflow."<namespace>\:<name>\:<version>.task.<taskName>".name

  2. Task-level medium — quarkus.flow.http.client.workflow."<namespace>\:<name>.task.<taskName>".name

  3. Task-level short — quarkus.flow.http.client.workflow."<name>.task.<taskName>".name

  4. Workflow-level full — quarkus.flow.http.client.workflow."<namespace>\:<name>\:<version>".name

  5. Workflow-level medium — quarkus.flow.http.client.workflow."<namespace>\:<name>".name

  6. Workflow-level short — quarkus.flow.http.client.workflow.<name>.name

  7. Default fallback — no routing configured; the global default client is used

Progressive specificity: The resolver tries keys from most to least specific: first task-level (full, medium, short), then workflow-level (full, medium, short). Within each group, it goes from longest (namespace:name:version) to shortest (name only).

Colons in the composite key must be escaped as \: in application.properties files. For example, for a workflow with namespace acme and name order-flow, use "acme\:order-flow".
It is highly recommended that you keep HTTP-related task names unique within your workflow to avoid routing conflicts.

5. Configure static headers

Use static-headers to attach headers to every request sent by a client (comma-separated):

# Default client
quarkus.flow.http.client.static-headers=X-Env=prod,X-Tenant=acme

# Named client
quarkus.flow.http.client.named.secureA.static-headers=X-Env=prod,X-Region=us-east-1

6. Logging and debugging HTTP requests

Enable the RESTEasy Reactive client logger to see the exact payloads on the wire:

# Log both request and response line + headers (+ body, up to limit)
quarkus.flow.http.client.logging.scope=request-response
quarkus.flow.http.client.logging.body-limit=1024

# Enable the REST client logger
quarkus.log.category."org.jboss.resteasy.reactive.client.logging".level=DEBUG

7. HTTP/2 and ALPN

quarkus.flow.http.client.http2=true
quarkus.flow.http.client.alpn=true

8. Proxy support

HTTP proxy support relies on quarkus-proxy-registry, which is currently experimental. This feature is not recommended for production environments as the API may change in future Quarkus versions.

Quarkus Flow integrates with the Quarkus Proxy Registry.

# 1. Configure the Proxy Registry
quarkus.proxy.registry.host=proxy.mycorp.internal
quarkus.proxy.registry.port=3128

# 2. Tell the default client to use it
quarkus.flow.http.client.proxy-configuration-name=none

# Or configure a named client to use a specific named proxy
quarkus.proxy.my-proxy.registry.host=proxy.mycorp.internal
quarkus.flow.http.client.named.secureA.proxy-configuration-name=my-proxy

9. Redirects, compression and chunk size

quarkus.flow.http.client.max-redirects=5
quarkus.flow.http.client.follow-redirects=true
quarkus.flow.http.client.enable-compression=true
quarkus.flow.http.client.max-chunk-size=16384

10. Multi-valued query parameters

# See MultiQueryParamMode enum in RESTEasy Reactive
quarkus.flow.http.client.multi-query-param-mode=multi

11. TLS, trust and host verification

# Trust all certificates (including self-signed)
quarkus.flow.http.client.trust-all=true

# Disable hostname verification
quarkus.flow.http.client.verify-host=false
Only enable trust-all or disable verify-host in controlled environments like local development.

See also