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

Table 4.3. Options for Configuring REST DSL

Java DSLXML DSLDescription
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. From Camel 2.17 RestHostNameResolver.allLocalIp can be used to resolve to all local IP addresses.
The default is localHostName up to Camel 2.16. From Camel 2.17 the default is allLocalIp.
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:
  • json.in
  • json.out
  • xml.in
  • xml.out
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.

Table 4.4. Default CORS Headers

Header KeyHeader 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.disableFeatures
  • json.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