// 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 a 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 reponse returned to the client when exceptions are thrown from your routes, then you can use Camel error handling constucts 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.

