// Do not edit directly!
// This file was generated by camel-quarkus-maven-plugin:update-extension-doc-page
[id="extensions-platform-http"]
= Platform HTTP
:page-aliases: extensions/platform-http.adoc
:linkattrs:
:cq-artifact-id: camel-quarkus-platform-http
:cq-native-supported: true
:cq-status: Stable
:cq-status-deprecation: Stable
:cq-description: Expose HTTP endpoints using the HTTP server available in the current platform.
:cq-deprecated: false
:cq-jvm-since: 0.3.0
:cq-native-since: 0.3.0

ifeval::[{doc-show-badges} == true]
[.badges]
[.badge-key]##JVM since##[.badge-supported]##0.3.0## [.badge-key]##Native since##[.badge-supported]##0.3.0##
endif::[]

This extension allows for creating HTTP endpoints for consuming HTTP requests.

It is built on top of the Eclipse Vert.x HTTP server provided by the `quarkus-vertx-http` extension.


[id="extensions-platform-http-whats-inside"]
== What's inside

* xref:{cq-camel-components}::platform-http-component.adoc[Platform HTTP component], URI syntax: `platform-http:path`

Please refer to the above link for usage and configuration details.

[id="extensions-platform-http-maven-coordinates"]
== Maven coordinates

https://{link-quarkus-code-generator}/?extension-search=camel-quarkus-platform-http[Create a new project with this extension on {link-quarkus-code-generator}, window="_blank"]

Or add the coordinates to your existing project:

[source,xml]
----
<dependency>
    <groupId>org.apache.camel.quarkus</groupId>
    <artifactId>camel-quarkus-platform-http</artifactId>
</dependency>
----
ifeval::[{doc-show-user-guide-link} == true]
Check the xref:user-guide/index.adoc[User guide] for more information about writing Camel Quarkus applications.
endif::[]

[id="extensions-platform-http-usage"]
== Usage
[id="extensions-platform-http-usage-basic-usage"]
=== Basic Usage

Serve all HTTP methods on the `/hello` endpoint:

[source,java]
----
from("platform-http:/hello").setBody(simple("Hello ${header.name}"));
----

Serve only GET requests on the `/hello` endpoint:

[source,java]
----
from("platform-http:/hello?httpMethodRestrict=GET").setBody(simple("Hello ${header.name}"));
----

[id="extensions-platform-http-usage-using-platform-http-via-camel-rest-dsl"]
=== Using `platform-http` via Camel REST DSL

To be able to use Camel REST DSL with the `platform-http` component, add `camel-quarkus-rest` to your `pom.xml`:

[source,xml]
----
<dependency>
    <groupId>org.apache.camel.quarkus</groupId>
    <artifactId>camel-quarkus-rest</artifactId>
</dependency>
----

Then you can use the Camel REST DSL:

[source,java]
----
rest()
    .get("/my-get-endpoint")
        .to("direct:handleGetRequest");

    .post("/my-post-endpoint")
        .to("direct:handlePostRequest");
----

[id="extensions-platform-http-usage-handling-multipart-form-data-file-uploads"]
=== Handling `multipart/form-data` file uploads

You can restrict the uploads to certain file extensions by white listing them:

[source,java]
----
from("platform-http:/upload/multipart?fileNameExtWhitelist=adoc,txt&httpMethodRestrict=POST")
    .to("log:multipart")
    .process(e -> {
        final AttachmentMessage am = e.getMessage(AttachmentMessage.class);
        if (am.hasAttachments()) {
            am.getAttachments().forEach((fileName, dataHandler) -> {
                try (InputStream in = dataHandler.getInputStream()) {
                    // do something with the input stream
                } catch (IOException ioe) {
                    throw new RuntimeException(ioe);
                }
            });
        }
    });
----

[id="extensions-platform-http-usage-securing-platform-http-endpoints"]
=== Securing `platform-http` endpoints

Quarkus provides a variety of security and authentication mechanisms which can be used to secure `platform-http` endpoints. Refer to the https://quarkus.io/guides/security[Quarkus Security documentation] for further details.

Within a route, it is possible to obtain the authenticated user and its associated `SecurityIdentity` and `Principal`:
[source,java]
----
from("platform-http:/secure")
    .process(e -> {
        Message message = e.getMessage();
        QuarkusHttpUser user = message.getHeader(VertxPlatformHttpConstants.AUTHENTICATED_USER, QuarkusHttpUser.class);
        SecurityIdentity securityIdentity = user.getSecurityIdentity();
        Principal principal = securityIdentity.getPrincipal();
        // Do something useful with SecurityIdentity / Principal. E.g check user roles etc.
    });
----

Also check the `quarkus.http.body.*` configuration options in
https://quarkus.io/guides/all-config#quarkus-vertx-http_quarkus-vertx-http-eclipse-vert.x-http[Quarkus documentation], esp. `quarkus.http.body.handle-file-uploads`, `quarkus.http.body.uploads-directory` and `quarkus.http.body.delete-uploaded-files-on-end`.

[id="extensions-platform-http-usage-implementing-a-reverse-proxy"]
=== Implementing a reverse proxy

Platform HTTP component can act as a reverse proxy, in that case `Exchange.HTTP_URI`, `Exchange.HTTP_HOST` headers are populated from the absolute URL received on the request line of the HTTP request.

Here's an example of an HTTP proxy that simply redirects the Exchange to the origin server.

[source,java]
----
from("platform-http:proxy")
    .toD("http://"
        + "${headers." + Exchange.HTTP_HOST + "}");
----

[id="extensions-platform-http-usage-error-handling"]
=== Error handling

If you need to customize the response returned to the client when exceptions are thrown from your routes, then you can use Camel error handling constructs like `doTry`, `doCatch` and `onException`.

For example, to configure a global exception handler in response to a specific Exception type being thrown.

[source,java]
----
onException(InvalidOrderTotalException.class)
    .handled(true)
    .setHeader(Exchange.HTTP_RESPONSE_CODE).constant(500)
    .setHeader(Exchange.CONTENT_TYPE).constant("text/plain")
    .setBody().constant("The order total was not greater than 100");

from("platform-http:/orders")
    .choice().when().xpath("//order/total > 100")
        .to("direct:processOrder")
    .otherwise()
        .throwException(new InvalidOrderTotalException());
----

You can implement more fine-grained error handling by hooking into the Vert.x Web router initialization with a CDI observer.

[source,java]
----
void initRouter(@Observes Router router) {
    // Custom 404 handler
    router.errorHandler(404, new Handler<RoutingContext>() {
        @Override
        public void handle(RoutingContext event) {
            event.response()
                .setStatusCode(404)
                .putHeader("Content-Type", "text/plain")
                .end("Sorry - resource not found");
        }
    });
}
----

Note that care should be taken when modifying the router configuration when extensions such as RestEASY are present, since they may register their own error handling logic.


[id="extensions-platform-http-additional-camel-quarkus-configuration"]
== Additional Camel Quarkus configuration

[id="extensions-platform-http-configuration-platform-http-server-configuration"]
=== Platform HTTP server configuration

Configuration of the platform HTTP server is managed by Quarkus. Refer to the https://quarkus.io/guides/all-config#quarkus-vertx-http_quarkus-vertx-http-eclipse-vert.x-http[Quarkus HTTP configuration guide]
for the full list of configuration options.

To configure SSL for the Platform HTTP server, follow the https://quarkus.io/guides/http-reference#ssl[secure connections with SSL guide].
Note that configuring the server for SSL with `SSLContextParameters` is not currently supported.

[id="extensions-platform-http-configuration-character-encodings"]
=== Character encodings

Check the xref:user-guide/native-mode.adoc#charsets[Character encodings section] of the Native mode guide if you expect
your application to send or receive requests using non-default encodings.

