<commit_before>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= Writing REST Services with RESTEasy Reactive

include::./attributes.adoc[]
:jaxrsapi: https://javadoc.io/doc/javax.ws.rs/javax.ws.rs-api/2.1.1
:jaxrsspec: /specs/jaxrs/2.1/index.html
:jdkapi: https://docs.oracle.com/en/java/javase/11/docs/api/java.base
:mutinyapi: https://smallrye.io/smallrye-mutiny/apidocs
:httpspec: https://tools.ietf.org/html/rfc7231
:jsonpapi: https://javadoc.io/doc/javax.json/javax.json-api/1.1.4
:vertxapi: https://javadoc.io/doc/io.vertx/vertx-core/latest/index.html
:resteasy-reactive-api: https://javadoc.io/doc/io.quarkus.resteasy.reactive/resteasy-reactive/{quarkus-version}
:resteasy-reactive-common-api: https://javadoc.io/doc/io.quarkus.resteasy.reactive/resteasy-reactive-common/{quarkus-version}

This guide explains how to write REST Services with RESTEasy Reactive in Quarkus.

[TIP]
====
This is the reference guide for RESTEasy Reactive.
For a more lightweight introduction, please refer to the xref:rest-json.adoc[Writing JSON REST services guides].
====

== What is RESTEasy Reactive?

RESTEasy Reactive is a new link:{jaxrsspec}[JAX-RS]
implementation written from the ground up to work on our
common https://vertx.io/[Vert.x] layer and is thus fully reactive, while also being very tightly integrated with
Quarkus and consequently moving a lot of work to build time.

You should be able to use it in place of any JAX-RS implementation, but on top of that it has
great performance for both blocking and non-blocking endpoints, and a lot of new features on top
of what JAX-RS provides.

== Writing endpoints

=== Getting started

Add the following import to your build file:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-reactive</artifactId>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("io.quarkus:quarkus-resteasy-reactive")
----

You can now write your first endpoint in the `org.acme.rest.Endpoint` class:

[source,java]
----
package org.acme.rest;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("")
public class Endpoint {

    @GET
    public String hello() {
        return "Hello, World!";
    }
}
----

=== Terminology

REST:: https://en.wikipedia.org/wiki/Representational_state_transfer[REpresentational State Transfer]
Endpoint:: Java method which is called to serve a REST call
URL / URI (Uniform Resource Locator / Identifier):: Used to identify the location of REST resources (https://tools.ietf.org/html/rfc7230#section-2.7[specification])
Resource:: Represents your domain object. This is what your API serves and modifies. Also called an `entity` in JAX-RS.
Representation:: How your resource is represented on the wire, can vary depending on content types
Content type:: Designates a particular representation (also called a media type), for example `text/plain` or `application/json`
HTTP:: Underlying wire protocol for routing REST calls (see https://tools.ietf.org/html/rfc7230[HTTP specifications])
HTTP request:: the request part of the HTTP call, consisting of an HTTP method, a target URI, headers and an optional message body
HTTP response:: the response part of the HTTP call, consisting of an HTTP response status, headers and an optional message body

=== Declaring endpoints: URI mapping

Any class annotated with a link:{jaxrsapi}/javax/ws/rs/Path.html[`@Path`] annotation can have its methods exposed as REST endpoints,
provided they have an HTTP method annotation (see below).

That link:{jaxrsapi}/javax/ws/rs/Path.html[`@Path`] annotation defines the URI prefix under which those methods will be exposed. It can
be empty, or contain a prefix such as `rest` or `rest/V1`.

Each exposed endpoint method can in turn have another link:{jaxrsapi}/javax/ws/rs/Path.html[`@Path`] annotation which adds to its containing
class annotation. For example, this defines a `rest/hello` endpoint:

[source,java]
----
package org.acme.rest;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("rest")
public class Endpoint {

    @Path("hello")
    @GET
    public String hello() {
        return "Hello, World!";
    }
}
----

See <<uri-parameters,URI parameters>> for more information about URI mapping.

You can set the root path for all rest endpoints using the `@ApplicationPath` annotation, as shown below.

[source,java]
----
package org.acme.rest;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/api")
public static class MyApplication extends Application {

}
----

This will cause all rest endpoints to be resolve relative to `/api`, so the endpoint above with `@Path("rest")` would
be accessible at `/api/rest/`. You can also set the `quarkus.resteasy-reactive.path` build time property to set the root path if you
don't want to use an annotation.

=== Declaring endpoints: HTTP methods

Each endpoint method must be annotated with one of the following annotations, which defines which HTTP
method will be mapped to the method:

.Table HTTP method annotations
|===
|Annotation|Usage 

|link:{jaxrsapi}/javax/ws/rs/GET.html[`@GET`]
|Obtain a resource representation, should not modify state, link:{httpspec}#section-4.2.2[idempotent] (link:{httpspec}#section-4.3.1[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/HEAD.html[`@HEAD`]
|Obtain metadata about a resource, similar to `GET` with no body (link:{httpspec}#section-4.3.2[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/POST.html[`@POST`]
|Create a resource and obtain a link to it (link:{httpspec}#section-4.3.3[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/PUT.html[`@PUT`]
|Replace a resource or create one, should be link:{httpspec}#section-4.2.2[idempotent] (link:{httpspec}#section-4.3.4[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/DELETE.html[`@DELETE`]
|Delete an existing resource, link:{httpspec}#section-4.2.2[idempotent]  (link:{httpspec}#section-4.3.5[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/OPTIONS.html[`@OPTIONS`]
|Obtain information about a resource, link:{httpspec}#section-4.2.2[idempotent] (link:{httpspec}#section-4.3.7[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/PATCH.html[`@PATCH`]
|Update a resource, or create one, not link:{httpspec}#section-4.2.2[idempotent] (https://tools.ietf.org/html/rfc5789#section-2[HTTP docs])

|===

You can also declare other HTTP methods by declaring them as an annotation with the
link:{jaxrsapi}/javax/ws/rs/HttpMethod.html[`@HttpMethod`] annotation:

[source,java]
----
package org.acme.rest;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

import javax.ws.rs.HttpMethod;
import javax.ws.rs.Path;

@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("CHEESE")
@interface CHEESE {
}

@Path("")
public class Endpoint {

    @CHEESE
    public String hello() {
        return "Hello, Cheese World!";
    }
}
----

=== Declaring endpoints: representation / content types

Each endpoint method may consume or produce specific resource representations, which are indicated by
the HTTP link:{httpspec}#section-3.1.1.5[`Content-Type`] header, which in turn contains 
link:{httpspec}#section-3.1.1.1[MIME (Media Type)] values, such as the following:

- `text/plain` which is the default for any endpoint returning a `String`.
- `text/html` for HTML (such as with xref:qute.adoc[Qute templating])
- `application/json` for a <<json,JSON REST endpoint>>
- `text/*` which is a sub-type wildcard for any text media type
- `\*/*` which is a wildcard for any media type

You may annotate your endpoint class with the link:{jaxrsapi}/javax/ws/rs/Produces.html[`@Produces`] 
or link:{jaxrsapi}/javax/ws/rs/Consumes.html[`@Consumes`] annotations, which
allow you to specify one or more media types that your endpoint may accept as HTTP request body
or produce as HTTP response body. Those class annotations apply to each method.

Any method may also be annotated with the link:{jaxrsapi}/javax/ws/rs/Produces.html[`@Produces`] 
or link:{jaxrsapi}/javax/ws/rs/Consumes.html[`@Consumes`] annotations, in which
case they override any eventual class annotation.

The link:{jaxrsapi}/javax/ws/rs/core/MediaType.html[`MediaType`] class has many constants you
can use to point to specific pre-defined media types.

See <<negotiation>> for more information.

=== Accessing request parameters

[[request-parameters]]

NOTE: don't forget to configure your compiler to generate parameter name information with `-parameters` (javac)
or `<parameters>` or `<maven.compiler.parameters>` (https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#parameters[Maven]).

The following HTTP request elements may be obtained by your endpoint method:

.Table HTTP request parameter annotations
|===
|HTTP element|Annotation|Usage 

|[[path-parameter]]Path parameter
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestPath.html[`@RestPath`] (or nothing)
|URI template parameter (simplified version of the https://tools.ietf.org/html/rfc6570[URI Template specification]), 
see <<uri-parameters,URI parameters>> for more information.

|Query parameter
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestQuery.html[`@RestQuery`]
|The value of a https://tools.ietf.org/html/rfc3986#section-3.4[URI query parameter]

|Header
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestHeader.html[`@RestHeader`]
|The value of an https://tools.ietf.org/html/rfc7230#section-3.2[HTTP header]

|Cookie
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestCookie.html[`@RestCookie`]
|The value of an https://tools.ietf.org/html/rfc6265#section-4.2[HTTP cookie]

|Form parameter
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestForm.html[`@RestForm`]
|The value of an https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST[HTTP URL-encoded FORM]

|Matrix parameter
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestMatrix.html[`@RestMatrix`]
|The value of an https://tools.ietf.org/html/rfc3986#section-3.3[URI path segment parameter]

|===

For each of those annotations, you may specify the name of the element they refer to, otherwise
they will use the name of the annotated method parameter.

If a client made the following HTTP call:

[source,http]
----
POST /cheeses;variant=goat/tomme?age=matured HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: level=hardcore
X-Cheese-Secret-Handshake: fist-bump

smell=strong
----

Then you could obtain all the various parameters with this endpoint method:

[source,java]
----
package org.acme.rest;

import javax.ws.rs.POST;
import javax.ws.rs.Path;

import org.jboss.resteasy.reactive.RestCookie;
import org.jboss.resteasy.reactive.RestForm;
import org.jboss.resteasy.reactive.RestHeader;
import org.jboss.resteasy.reactive.RestMatrix;
import org.jboss.resteasy.reactive.RestPath;
import org.jboss.resteasy.reactive.RestQuery;

@Path("/cheeses/{type}")
public class Endpoint {

    @POST
    public String allParams(@RestPath String type,
                            @RestMatrix String variant,
                            @RestQuery String age,
                            @RestCookie String level,
                            @RestHeader("X-Cheese-Secret-Handshake")
                            String secretHandshake,
                            @RestForm String smell) {
        return type + "/" + variant + "/" + age + "/" + level + "/" + secretHandshake + "/" + smell;
    }
}
----

NOTE: the link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestPath.html[`@RestPath`]
annotation is optional: any parameter whose name matches an existing URI
template variable will be automatically assumed to have link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestPath.html[`@RestPath`].

You can also use any of the JAX-RS annotations link:{jaxrsapi}/javax/ws/rs/PathParam.html[`@PathParam`],
link:{jaxrsapi}/javax/ws/rs/QueryParam.html[`@QueryParam`],
link:{jaxrsapi}/javax/ws/rs/HeaderParam.html[`@HeaderParam`],
link:{jaxrsapi}/javax/ws/rs/CookieParam.html[`@CookieParam`],
link:{jaxrsapi}/javax/ws/rs/FormParam.html[`@FormParam`] or
link:{jaxrsapi}/javax/ws/rs/MatrixParam.html[`@MatrixParam`] for this,
but they require you to specify the parameter name.

See <<parameter-mapping>> for more advanced use-cases.

=== Declaring URI parameters

[[uri-parameters]]

You can declare URI parameters and use regular expressions in your path, so for instance
the following endpoint will serve requests for `/hello/stef/23` and `/hello` but not
`/hello/stef/0x23`:

[source,java]
----
package org.acme.rest;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("hello")
public class Endpoint {

    @Path("{name}/{age:\\d+}")
    @GET
    public String personalisedHello(String name, int age) {
        return "Hello " + name + " is your age really " + age + "?";
    }

    @GET
    public String genericHello() {
        return "Hello stranger";
    }
}
----


=== Accessing the request body

Any method parameter with no annotation will receive the method body.footnote:[Unless it is a
<<path-parameter,URI template parameter>> or a <<context-objects,context object>>.], after it has been mapped from
its HTTP representation to the Java type of the parameter.

The following parameter types will be supported out of the box:

[[resource-types]]

.Table Request body parameter type
|===
|Type|Usage

|link:{jdkapi}/java/io/File.html[`File`]
|The entire request body in a temporary file

|`byte[]`
|The entire request body, not decoded

|`char[]`
|The entire request body, decoded

|link:{jdkapi}/java/lang/String.html[`String`]
|The entire request body, decoded

|link:{jdkapi}/java/io/InputStream.html[`InputStream`]
|The request body in a blocking stream

|link:{jdkapi}/java/io/Reader.html[`Reader`]
|The request body in a blocking stream

|All Java primitives and their wrapper classes
|Java primitive types

|link:{jdkapi}/java/math/BigDecimal.html[`BigDecimal`], link:{jdkapi}/java/math/BigInteger.html[`BigInteger`]
|Large integers and decimals.

|link:{jsonpapi}/javax/json/JsonArray.html[`JsonArray`], link:{jsonpapi}/javax/json/JsonArray.html[`JsonObject`],
link:{jsonpapi}/javax/json/JsonArray.html[`JsonStructure`], link:{jsonpapi}/javax/json/JsonArray.html[`JsonValue`]
|JSON value types  

|link:{vertxapi}io/vertx/core/buffer/Buffer.html[`Buffer`]
|Vert.x Buffer 

|any other type
|Will be <<json,mapped from JSON to that type>>

|===

NOTE: You can add support for more <<readers-writers,body parameter types>>.

[[multipart]]
=== Handling Multipart Form data

To handle HTTP requests that have `multipart/form-data` as their content type, RESTEasy Reactive introduces the 
link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/MultipartForm.html[`@MultipartForm`] annotation.
Let us look at an example of its use.

Assuming an HTTP request containing a file upload and a form value containing a string description need to be handled, we could write a POJO
that will hold this information like so:

[source,java]
----
import javax.ws.rs.core.MediaType;

import org.jboss.resteasy.reactive.PartType;
import org.jboss.resteasy.reactive.RestForm;<commit_msg>fix: links for JSON value types<commit_after>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= Writing REST Services with RESTEasy Reactive

include::./attributes.adoc[]
:jaxrsapi: https://javadoc.io/doc/javax.ws.rs/javax.ws.rs-api/2.1.1
:jaxrsspec: /specs/jaxrs/2.1/index.html
:jdkapi: https://docs.oracle.com/en/java/javase/11/docs/api/java.base
:mutinyapi: https://smallrye.io/smallrye-mutiny/apidocs
:httpspec: https://tools.ietf.org/html/rfc7231
:jsonpapi: https://javadoc.io/doc/javax.json/javax.json-api/1.1.4
:vertxapi: https://javadoc.io/doc/io.vertx/vertx-core/latest/index.html
:resteasy-reactive-api: https://javadoc.io/doc/io.quarkus.resteasy.reactive/resteasy-reactive/{quarkus-version}
:resteasy-reactive-common-api: https://javadoc.io/doc/io.quarkus.resteasy.reactive/resteasy-reactive-common/{quarkus-version}

This guide explains how to write REST Services with RESTEasy Reactive in Quarkus.

[TIP]
====
This is the reference guide for RESTEasy Reactive.
For a more lightweight introduction, please refer to the xref:rest-json.adoc[Writing JSON REST services guides].
====

== What is RESTEasy Reactive?

RESTEasy Reactive is a new link:{jaxrsspec}[JAX-RS]
implementation written from the ground up to work on our
common https://vertx.io/[Vert.x] layer and is thus fully reactive, while also being very tightly integrated with
Quarkus and consequently moving a lot of work to build time.

You should be able to use it in place of any JAX-RS implementation, but on top of that it has
great performance for both blocking and non-blocking endpoints, and a lot of new features on top
of what JAX-RS provides.

== Writing endpoints

=== Getting started

Add the following import to your build file:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-reactive</artifactId>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("io.quarkus:quarkus-resteasy-reactive")
----

You can now write your first endpoint in the `org.acme.rest.Endpoint` class:

[source,java]
----
package org.acme.rest;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("")
public class Endpoint {

    @GET
    public String hello() {
        return "Hello, World!";
    }
}
----

=== Terminology

REST:: https://en.wikipedia.org/wiki/Representational_state_transfer[REpresentational State Transfer]
Endpoint:: Java method which is called to serve a REST call
URL / URI (Uniform Resource Locator / Identifier):: Used to identify the location of REST resources (https://tools.ietf.org/html/rfc7230#section-2.7[specification])
Resource:: Represents your domain object. This is what your API serves and modifies. Also called an `entity` in JAX-RS.
Representation:: How your resource is represented on the wire, can vary depending on content types
Content type:: Designates a particular representation (also called a media type), for example `text/plain` or `application/json`
HTTP:: Underlying wire protocol for routing REST calls (see https://tools.ietf.org/html/rfc7230[HTTP specifications])
HTTP request:: the request part of the HTTP call, consisting of an HTTP method, a target URI, headers and an optional message body
HTTP response:: the response part of the HTTP call, consisting of an HTTP response status, headers and an optional message body

=== Declaring endpoints: URI mapping

Any class annotated with a link:{jaxrsapi}/javax/ws/rs/Path.html[`@Path`] annotation can have its methods exposed as REST endpoints,
provided they have an HTTP method annotation (see below).

That link:{jaxrsapi}/javax/ws/rs/Path.html[`@Path`] annotation defines the URI prefix under which those methods will be exposed. It can
be empty, or contain a prefix such as `rest` or `rest/V1`.

Each exposed endpoint method can in turn have another link:{jaxrsapi}/javax/ws/rs/Path.html[`@Path`] annotation which adds to its containing
class annotation. For example, this defines a `rest/hello` endpoint:

[source,java]
----
package org.acme.rest;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("rest")
public class Endpoint {

    @Path("hello")
    @GET
    public String hello() {
        return "Hello, World!";
    }
}
----

See <<uri-parameters,URI parameters>> for more information about URI mapping.

You can set the root path for all rest endpoints using the `@ApplicationPath` annotation, as shown below.

[source,java]
----
package org.acme.rest;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/api")
public static class MyApplication extends Application {

}
----

This will cause all rest endpoints to be resolve relative to `/api`, so the endpoint above with `@Path("rest")` would
be accessible at `/api/rest/`. You can also set the `quarkus.resteasy-reactive.path` build time property to set the root path if you
don't want to use an annotation.

=== Declaring endpoints: HTTP methods

Each endpoint method must be annotated with one of the following annotations, which defines which HTTP
method will be mapped to the method:

.Table HTTP method annotations
|===
|Annotation|Usage 

|link:{jaxrsapi}/javax/ws/rs/GET.html[`@GET`]
|Obtain a resource representation, should not modify state, link:{httpspec}#section-4.2.2[idempotent] (link:{httpspec}#section-4.3.1[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/HEAD.html[`@HEAD`]
|Obtain metadata about a resource, similar to `GET` with no body (link:{httpspec}#section-4.3.2[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/POST.html[`@POST`]
|Create a resource and obtain a link to it (link:{httpspec}#section-4.3.3[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/PUT.html[`@PUT`]
|Replace a resource or create one, should be link:{httpspec}#section-4.2.2[idempotent] (link:{httpspec}#section-4.3.4[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/DELETE.html[`@DELETE`]
|Delete an existing resource, link:{httpspec}#section-4.2.2[idempotent]  (link:{httpspec}#section-4.3.5[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/OPTIONS.html[`@OPTIONS`]
|Obtain information about a resource, link:{httpspec}#section-4.2.2[idempotent] (link:{httpspec}#section-4.3.7[HTTP docs])

|link:{jaxrsapi}/javax/ws/rs/PATCH.html[`@PATCH`]
|Update a resource, or create one, not link:{httpspec}#section-4.2.2[idempotent] (https://tools.ietf.org/html/rfc5789#section-2[HTTP docs])

|===

You can also declare other HTTP methods by declaring them as an annotation with the
link:{jaxrsapi}/javax/ws/rs/HttpMethod.html[`@HttpMethod`] annotation:

[source,java]
----
package org.acme.rest;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

import javax.ws.rs.HttpMethod;
import javax.ws.rs.Path;

@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("CHEESE")
@interface CHEESE {
}

@Path("")
public class Endpoint {

    @CHEESE
    public String hello() {
        return "Hello, Cheese World!";
    }
}
----

=== Declaring endpoints: representation / content types

Each endpoint method may consume or produce specific resource representations, which are indicated by
the HTTP link:{httpspec}#section-3.1.1.5[`Content-Type`] header, which in turn contains 
link:{httpspec}#section-3.1.1.1[MIME (Media Type)] values, such as the following:

- `text/plain` which is the default for any endpoint returning a `String`.
- `text/html` for HTML (such as with xref:qute.adoc[Qute templating])
- `application/json` for a <<json,JSON REST endpoint>>
- `text/*` which is a sub-type wildcard for any text media type
- `\*/*` which is a wildcard for any media type

You may annotate your endpoint class with the link:{jaxrsapi}/javax/ws/rs/Produces.html[`@Produces`] 
or link:{jaxrsapi}/javax/ws/rs/Consumes.html[`@Consumes`] annotations, which
allow you to specify one or more media types that your endpoint may accept as HTTP request body
or produce as HTTP response body. Those class annotations apply to each method.

Any method may also be annotated with the link:{jaxrsapi}/javax/ws/rs/Produces.html[`@Produces`] 
or link:{jaxrsapi}/javax/ws/rs/Consumes.html[`@Consumes`] annotations, in which
case they override any eventual class annotation.

The link:{jaxrsapi}/javax/ws/rs/core/MediaType.html[`MediaType`] class has many constants you
can use to point to specific pre-defined media types.

See <<negotiation>> for more information.

=== Accessing request parameters

[[request-parameters]]

NOTE: don't forget to configure your compiler to generate parameter name information with `-parameters` (javac)
or `<parameters>` or `<maven.compiler.parameters>` (https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#parameters[Maven]).

The following HTTP request elements may be obtained by your endpoint method:

.Table HTTP request parameter annotations
|===
|HTTP element|Annotation|Usage 

|[[path-parameter]]Path parameter
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestPath.html[`@RestPath`] (or nothing)
|URI template parameter (simplified version of the https://tools.ietf.org/html/rfc6570[URI Template specification]), 
see <<uri-parameters,URI parameters>> for more information.

|Query parameter
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestQuery.html[`@RestQuery`]
|The value of a https://tools.ietf.org/html/rfc3986#section-3.4[URI query parameter]

|Header
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestHeader.html[`@RestHeader`]
|The value of an https://tools.ietf.org/html/rfc7230#section-3.2[HTTP header]

|Cookie
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestCookie.html[`@RestCookie`]
|The value of an https://tools.ietf.org/html/rfc6265#section-4.2[HTTP cookie]

|Form parameter
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestForm.html[`@RestForm`]
|The value of an https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST[HTTP URL-encoded FORM]

|Matrix parameter
|link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestMatrix.html[`@RestMatrix`]
|The value of an https://tools.ietf.org/html/rfc3986#section-3.3[URI path segment parameter]

|===

For each of those annotations, you may specify the name of the element they refer to, otherwise
they will use the name of the annotated method parameter.

If a client made the following HTTP call:

[source,http]
----
POST /cheeses;variant=goat/tomme?age=matured HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: level=hardcore
X-Cheese-Secret-Handshake: fist-bump

smell=strong
----

Then you could obtain all the various parameters with this endpoint method:

[source,java]
----
package org.acme.rest;

import javax.ws.rs.POST;
import javax.ws.rs.Path;

import org.jboss.resteasy.reactive.RestCookie;
import org.jboss.resteasy.reactive.RestForm;
import org.jboss.resteasy.reactive.RestHeader;
import org.jboss.resteasy.reactive.RestMatrix;
import org.jboss.resteasy.reactive.RestPath;
import org.jboss.resteasy.reactive.RestQuery;

@Path("/cheeses/{type}")
public class Endpoint {

    @POST
    public String allParams(@RestPath String type,
                            @RestMatrix String variant,
                            @RestQuery String age,
                            @RestCookie String level,
                            @RestHeader("X-Cheese-Secret-Handshake")
                            String secretHandshake,
                            @RestForm String smell) {
        return type + "/" + variant + "/" + age + "/" + level + "/" + secretHandshake + "/" + smell;
    }
}
----

NOTE: the link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestPath.html[`@RestPath`]
annotation is optional: any parameter whose name matches an existing URI
template variable will be automatically assumed to have link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/RestPath.html[`@RestPath`].

You can also use any of the JAX-RS annotations link:{jaxrsapi}/javax/ws/rs/PathParam.html[`@PathParam`],
link:{jaxrsapi}/javax/ws/rs/QueryParam.html[`@QueryParam`],
link:{jaxrsapi}/javax/ws/rs/HeaderParam.html[`@HeaderParam`],
link:{jaxrsapi}/javax/ws/rs/CookieParam.html[`@CookieParam`],
link:{jaxrsapi}/javax/ws/rs/FormParam.html[`@FormParam`] or
link:{jaxrsapi}/javax/ws/rs/MatrixParam.html[`@MatrixParam`] for this,
but they require you to specify the parameter name.

See <<parameter-mapping>> for more advanced use-cases.

=== Declaring URI parameters

[[uri-parameters]]

You can declare URI parameters and use regular expressions in your path, so for instance
the following endpoint will serve requests for `/hello/stef/23` and `/hello` but not
`/hello/stef/0x23`:

[source,java]
----
package org.acme.rest;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("hello")
public class Endpoint {

    @Path("{name}/{age:\\d+}")
    @GET
    public String personalisedHello(String name, int age) {
        return "Hello " + name + " is your age really " + age + "?";
    }

    @GET
    public String genericHello() {
        return "Hello stranger";
    }
}
----


=== Accessing the request body

Any method parameter with no annotation will receive the method body.footnote:[Unless it is a
<<path-parameter,URI template parameter>> or a <<context-objects,context object>>.], after it has been mapped from
its HTTP representation to the Java type of the parameter.

The following parameter types will be supported out of the box:

[[resource-types]]

.Table Request body parameter type
|===
|Type|Usage

|link:{jdkapi}/java/io/File.html[`File`]
|The entire request body in a temporary file

|`byte[]`
|The entire request body, not decoded

|`char[]`
|The entire request body, decoded

|link:{jdkapi}/java/lang/String.html[`String`]
|The entire request body, decoded

|link:{jdkapi}/java/io/InputStream.html[`InputStream`]
|The request body in a blocking stream

|link:{jdkapi}/java/io/Reader.html[`Reader`]
|The request body in a blocking stream

|All Java primitives and their wrapper classes
|Java primitive types

|link:{jdkapi}/java/math/BigDecimal.html[`BigDecimal`], link:{jdkapi}/java/math/BigInteger.html[`BigInteger`]
|Large integers and decimals.

|link:{jsonpapi}/javax/json/JsonArray.html[`JsonArray`], link:{jsonpapi}/javax/json/JsonObject.html[`JsonObject`],
link:{jsonpapi}/javax/json/JsonStructure.html[`JsonStructure`], link:{jsonpapi}/javax/json/JsonValue.html[`JsonValue`]
|JSON value types  

|link:{vertxapi}io/vertx/core/buffer/Buffer.html[`Buffer`]
|Vert.x Buffer 

|any other type
|Will be <<json,mapped from JSON to that type>>

|===

NOTE: You can add support for more <<readers-writers,body parameter types>>.

[[multipart]]
=== Handling Multipart Form data

To handle HTTP requests that have `multipart/form-data` as their content type, RESTEasy Reactive introduces the 
link:{resteasy-reactive-common-api}/org/jboss/resteasy/reactive/MultipartForm.html[`@MultipartForm`] annotation.
Let us look at an example of its use.

Assuming an HTTP request containing a file upload and a form value containing a string description need to be handled, we could write a POJO
that will hold this information like so:

[source,java]
----
import javax.ws.rs.core.MediaType;

import org.jboss.resteasy.reactive.PartType;
import org.jboss.resteasy.reactive.RestForm;
{'fraction_non_alphanumeric': 0.1271348478465178, 'fraction_numerical': 0.00687040217778786, 'mean_word_length': 4.588192683810214, 'pattern_counts': {'":': 0, '<': 55, '<?xml version=': 0, '>': 55, 'https://': 42, 'lorem ipsum': 0, 'www.': 2, 'xml': 4}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3511453', 'n_tokens_mistral': 10049, 'n_tokens_neox': 9565, 'n_words': 2842}