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

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

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