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