HTTP Reference

If you are looking to use Quarkus for a web application, look at the Quarkus for the Web guide.

By default, Quarkus will serve content from under the root context. If you want to change this you can use the quarkus.http.root-path config key to set the context path.

If you are using Servlet you can control the Servlet context path via quarkus.servlet.context-path. This item is relative to the http root above, and will only affect Servlet and things that run on top of Servlet. Most applications will want to use the HTTP root as this affects everything that Quarkus serves.

If both are specified then all non-Servlet web endpoints will be relative to quarkus.http.root-path, while Servlet’s will be served relative to {quarkus.http.root-path}/{quarkus.servlet.context-path}.

If REST Assured is used for testing and quarkus.http.root-path is set then Quarkus will automatically configure the base URL for use in Quarkus tests, so test URL’s should not include the root path.

In general, path configurations for web content are interpreted relative to quarkus.http.root-path (which is / by default).

As an example, if an extension configures a service path, that endpoint will be served from ${quarkus.http.root-path}/service. If you change the configuration of that path to /service, that endpoint will be served from /service.

The Path Resolution in Quarkus blog post further explains how path resolution works for both user and extension defined paths.

To have Quarkus support secure connections, you must either provide a certificate and associated key file, or supply a keystore.

In both cases, a password must be provided. See the designated paragraph for a detailed description of how to provide it.

To enable HTTP headers to be sent on every response, add the following properties:

This will include the X-Content-Type-Options: nosniff HTTP Header on responses for requests performed on any resource in the application.

You can also specify a path pattern and the HTTP methods the header needs to be applied:

This will apply the Pragma header only when the /headers/pragma resource is called with a GET or a HEAD method

To support 100-continue, the quarkus.http.handle-100-continue-automatically option needs to be enabled explicitly For additional information check 100-continue and the related Vert.x documentation.

HTTP/2 is enabled by default, and will be used by browsers if SSL is in use. Even if SSL is not in use HTTP/2 via cleartext upgrade is supported, and may be used by non-browser clients.

If you want to disable HTTP/2 you can set:

Note that some configuration attributes are specific to HTTP/2. For example, to configure the max header list size (~ header), you need to configure the quarkus.http.limits.max-header-list-size attribute. You can also enable or disable HTTP/2 push using quarkus.http.http2-push-enabled.

If you don’t want to specify a port you can set quarkus.http.port=0 or quarkus.http.test-port=0. A random open port will be picked by the OS, and a log message printed in the console. When the port is bound the quarkus.http.port system property will be set to the actual port that was selected, so you can use this to get the actual port number from inside the application. If you are in a test you can inject the URL normally and this will be configured with the actual port, and REST Assured will also be configured appropriately.

To make your Quarkus application accessible to another application running on a different domain, you need to configure cross-origin resource sharing (CORS). For more information about the CORS filter that Quarkus provides, see the Quarkus CORS filter section of the "Cross-origin resource sharing" guide.

Traffic shaping allows you to limit the bandwidth across all channels (i.e. connections), regardless of the number of open channels. This can be useful when you want to control the overall network traffic to prevent congestion or prioritize certain types of traffic.

To enable traffic shaping, add the following property in your application configuration:

The traffic shaping allows you to configure various parameters, such as write and read limitations (in bytes per second), check interval (the delay between two computations of the bandwidth), and maximum time to wait:

The check interval represents the period at which the traffic is computed, and a higher interval may result in less precise traffic shaping. Despite 0 being accepted (no accounting), it is recommended to set a positive value for the check interval, even if it is high since the precision of the traffic shaping depends on the period where the traffic is computed. In this case, a suggested value is something close to 5 or 10 minutes.

The outbound-global-bandwidth and inbound-global-bandwidth parameters represent the maximum number of bytes per second for write and read operations, respectively. You shall also consider to have object size in read or write operations relatively adapted to the bandwidth you required. For instance having 10 MB objects for 10KB/s will lead to burst effect, while having 100 KB objects for 1 MB/s should be smoothly handle by the traffic shaping.

Additionally, you can set the maximum time to wait (max-delay), which specifies an upper bound for time shaping. By default, it is set to 15 seconds. It must be less than the HTTP timeout. When one of the threshold is reached, no write happens for that period of time.

You can add HTTP request logging by configuring it in application.properties. There are two options for logging, either logging to the standard JBoss logging output, or logging to a dedicated file.

Set quarkus.http.access-log.consolidate-rerouted-requests=true to enable support for the modifier <. This modifier can be used for requests that have been internally redirected to consult the original request. The following attributes support this modifier:

Quarkus allows users to arbitrarily customize the options of HTTP servers started by Quarkus via the use of io.quarkus.vertx.http.HttpServerOptionsCustomizer. For example, if the HTTP port needs to be set programmatically, then the following code could be used:

In order to execute some custom action when the HTTP server is started you’ll need to declare an asynchronous CDI observer method. Quarkus asynchronously fires CDI events of types io.quarkus.vertx.http.HttpServerStart, io.quarkus.vertx.http.HttpsServerStart and io.quarkus.vertx.http.DomainSocketServerStart when the corresponding HTTP server starts listening on the configured host and port.

Quarkus could be accessed through proxies that additionally generate headers (e.g. X-Forwarded-Host) to keep information from the client-facing side of the proxy servers that is altered or lost when they are involved. In those scenarios, Quarkus can be configured to automatically update information like protocol, host, port and URI reflecting the values in these headers.

To set up this feature, please include the following lines in src/main/resources/application.properties:

To consider only de-facto standard header (Forwarded header), please include the following lines in src/main/resources/application.properties:

To consider only non-standard headers, please include the following lines instead in src/main/resources/application.properties:

Both configurations related to standard and non-standard headers can be combined, although the standard headers configuration will have precedence. However, combining them has security implications as clients can forge requests with a forwarded header that is not overwritten by the proxy. Therefore, proxies should strip unexpected X-Forwarded or X-Forwarded-* headers from the client.

Supported forwarding address headers are:

One can easily add a SameSite cookie property to any of the cookies set by a Quarkus endpoint by listing a cookie name and a SameSite attribute, for example:

Given this configuration, the jwt cookie will have a SameSite=Lax attribute and the session cookie will have a SameSite=Strict attribute.

To use Servlet you need to explicitly include quarkus-undertow: