docs/modules/ROOT/pages/reference/extensions/platform-http.adoc

// Do not edit directly!
// This file was generated by camel-quarkus-maven-plugin:update-extension-doc-page
= 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

[.badges]
[.badge-key]##JVM since##[.badge-supported]##0.3.0## [.badge-key]##Native since##[.badge-supported]##0.3.0##

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.


== 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.

== Maven coordinates

https://code.quarkus.io/?extension-search=camel-quarkus-platform-http[Create a new project with this extension on code.quarkus.io, 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>
----

Check the xref:user-guide/index.adoc[User guide] for more information about writing Camel Quarkus applications.

== 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}"));
----

=== 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");
----

=== 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);
                }
            });
        }
    });
----

=== 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`.


== Additional Camel Quarkus 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.

=== 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.