4.4. Configuring the REST DSL
Configuring with Java
In Java, you can configure the REST DSL using the
restConfiguration() builder API. For example, to configure the REST DSL to use the Servlet component as the underlying implementation:
restConfiguration().component("servlet").bindingMode("json").port("8181")
.contextPath("/camel-example-servlet-rest-blueprint/rest");Configuring with XML
In XML, you can configure the REST DSL using the
restConfiguration element. For example, to configure the REST DSL to use the Servlet component as the underlying implementation:
<?xml version="1.0" encoding="UTF-8"?>
<blueprint ...>
...
<camelContext xmlns="http://camel.apache.org/schema/blueprint">
...
<restConfiguration component="servlet"
bindingMode="json"
contextPath="/camel-example-servlet-rest-blueprint/rest"
port="8181">
<dataFormatProperty key="prettyPrint" value="true"/>
</restConfiguration>
...
</camelContext>
</blueprint>Configuration options
Table 4.3, “Options for Configuring REST DSL” shows options for configuring the REST DSL using the
restConfiguration() builder (Java DSL) or the restConfiguration element (XML DSL).
| Java DSL | XML DSL | Description |
|---|---|---|
component() | @component |
Specifies the Camel component to use as the REST transport (for example,
servlet, restlet, spark-rest, and so on). The value can either be the standard component name or the bean ID of a custom instance. If this option is not specified, Camel looks for an instance of RestConsumerFactory on the classpath or in the bean registry.
|
scheme() | @scheme |
The protocol to use for exposing the REST service. Depends on the underlying REST implementation, but
http and https are usually supported. Default is http.
|
host() | @host |
The hostname to use for exposing the REST service.
|
port() | @port |
The port number to use for exposing the REST service.
Note: This setting is ignored by the Servlet component, which uses the container's standard HTTP port instead. In the case of the Apache Karaf OSGi container, the standard HTTP port is normally 8181. It is good practice to set the port value nonetheless, for the sake of JMX and tooling.
|
contextPath() | @contextPath | Sets a leading context path for the REST services. This can be used with components such as Servlet, where the deployed Web application is deployed using a context-path setting. |
hostNameResolver() | @hostNameResolver |
If a hostname is not set explicitly, this resolver determines the host for the REST service. Possible values are
RestHostNameResolver.localHostName (Java DSL) or localHostName (XML DSL), which resolves to the host name format; and RestHostNameResolver.localIp (Java DSL) or localIp (XML DSL), which resolves to the dotted decimal IP address format. Default is localHostName.
|
bindingMode() | @bindingMode | Enables binding mode for JSON or XML format messages. Possible values are: off, auto, json, xml, or json_xml. Default is off. |
skipBindingOnErrorCode() | @skipBindingOnErrorCode |
Specifies whether to skip binding on output, if there is a custom HTTP error code header. This allows you to build custom error messages that do not bind to JSON or XML, as successful messages would otherwise do. Default is
true.
|
enableCORS() | @enableCORS | If true, enables CORS (cross-origin resource sharing) headers in the HTTP response. Default is false. |
jsonDataFormat() | @jsonDataFormat |
Specifies the component that Camel uses to implement the JSON data format. Possible values are:
json-jackson, json-gson, json-xstream. Default is json-jackson.
|
xmlDataFormat() | @xmlDataFormat |
Specifies the component that Camel uses to implement the XML data format. Possible value is:
jaxb. Default is jaxb.
|
componentProperty() | componentProperty | Enables you to set arbitrary component level properties on the underlying REST implementation. |
endpointProperty() | endpointProperty | Enables you to set arbitrary endpoint level properties on the underlying REST implementation. |
consumerProperty() | consumerProperty | Enables you to set arbitrary consumer endpoint properties on the underlying REST implementation. |
dataFormatProperty() | dataFormatProperty |
Enables you to set arbitrary properties on the underlying data format component (for example, Jackson or JAXB). From Camel 2.14.1 onwards, you can attach the following prefixes to the property keys:
To restrict the property setting to a specific format type (JSON or XML) and a particular message direction (IN or OUT).
|
corsHeaderProperty() | corsHeaders | Enables you to specify custom CORS headers, as key/value pairs. |
Default CORS headers
If CORS (cross-origin resource sharing) is enabled, the following headers are set by default. You can optionally override the default settings, by invoking the
corsHeaderProperty DSL command.
| Header Key | Header Value |
|---|---|
Access-Control-Allow-Origin | * |
Access-Control-Allow-Methods | GET, HEAD, POST, PUT, DELETE, TRACE, OPTIONS, CONNECT, PATCH
|
Access-Control-Allow-Headers | Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers
|
Access-Control-Max-Age | 3600 |
Enabling or disabling Jackson JSON features
You can enable or disable specific Jackson JSON features by configuring the following keys in the
dataFormatProperty option:
json.in.disableFeaturesjson.in.enableFeatures
For example, to disable Jackson's
FAIL_ON_UNKNOWN_PROPERTIES feature (which causes Jackson to fail if a JSON input has a property that cannot be mapped to a Java object):
restConfiguration().component("jetty")
.host("localhost").port(getPort())
.bindingMode(RestBindingMode.json)
.dataFormatProperty("json.in.disableFeatures", "FAIL_ON_UNKNOWN_PROPERTIES");
You can disable multiple features by specifying a comma-separated list. For example:
.dataFormatProperty("json.in.disableFeatures", "FAIL_ON_UNKNOWN_PROPERTIES,ADJUST_DATES_TO_CONTEXT_TIME_ZONE");
Here is an example that shows how to disable and enable Jackson JSON features in the Java DSL:
restConfiguration().component("jetty")
.host("localhost").port(getPort())
.bindingMode(RestBindingMode.json)
.dataFormatProperty("json.in.disableFeatures", "FAIL_ON_UNKNOWN_PROPERTIES,ADJUST_DATES_TO_CONTEXT_TIME_ZONE")
.dataFormatProperty("json.in.enableFeatures", "FAIL_ON_NUMBERS_FOR_ENUMS,USE_BIG_DECIMAL_FOR_FLOATS");
Here is an example that shows how to disable and enable Jackson JSON features in the XML DSL:
<restConfiguration component="jetty" host="localhost" port="9090" bindingMode="json"> <dataFormatProperty key="json.in.disableFeatures" value="FAIL_ON_UNKNOWN_PROPERTIES,ADJUST_DATES_TO_CONTEXT_TIME_ZONE"/> <dataFormatProperty key="json.in.enableFeatures" value="FAIL_ON_NUMBERS_FOR_ENUMS,USE_BIG_DECIMAL_FOR_FLOATS"/> </restConfiguration>
The Jackson features that can be disabled or enabled correspond to the
enum IDs from the following Jackson classes
