Since the release 2.15 of Apache Camel, a new Domain Specific Language or DSL has been developed to simplify the definition/creation of the REST endpoints and their syntax. This DSL syntax contains 2 words that we will use to :

• Configure the component and endpoint (restConfiguration())
• Define the action to be performed (GET, PUT, POST or DELETE) and path to access the service (rest().verb())

The syntax exists in Java or in XML format. Here is a an example where the path of the application is defined to access this URL resource “/blog” and where the HTTP verb “put” is defined for the the subpath “/article”. A parameter has been added using as convention the syntax “{id}”. The format to be used when the HTTP endpoint produce an HTTP Response or process a HTTP request can be specified as you can see using “produces(“”)” or “consumes(“”).

rest("/blog/").id("rest-blog-service")
       .produces("application/json")
       .consumes("application/json")

       .put("/article/{id}").id("rest-put-article")
       .type(Blog.class)
       .to("direct:add");

The formal descritpion of the REST DSL language is designed here

One of the benefit of the DSL is that it does not rely on any Java Specification (jax-rs 1.0, …) and annotations but allows to design in one place the services to be mapped/exposed behind the REST endpoints. The second benefit is that the syntax is supported by many Apache Camel components and by consequence, you have the possibility to design your project using one for them or to combine them.

• camel-netty-http
• camel-netty4-http
• camel-jetty
• camel-restlet
• camel-servlet
• camel-spark-rest
• camel-undertow

To configure the component/endpoint and their corresponding properties (enable CORS, port, hostname, contextPath, bindingMode, …), you will use the restConfigure() DSL word as showed hereafter

restConfiguration().component("servlet")
   .enableCORS(true)
   .bindingMode(RestBindingMode.json)
   .dataFormatProperty("prettyPrint", "true");

So, when Apache Camel will read the Java REST DSL or XML DSL syntax, it will instantiate using the factory class of the component selected an endpoint, set the fields of the component or endpoint object and next a HTTP handler responsible to process for a specific URL path the processing of the HTTP Request and HTTP response will be created and registered within the corresponding HTTP Web container.

Remark : As the implementation of the HTTP handler like also the verbs used (OPTION, CORS) is component dependent, I recommend that you evaluate them to verify/validate the one which is able to best process your HTTP requests.

To help you to work with this new REST DSL syntax, this project hosted on FuseByExample github repository has been created.

It provides a real application designed to manage Blog Articles (Create, Search, Delete). It will allow you to post Blog Article that we save into an ElasticSearch backend. The result posted within the NoSQL JSon Databae can be consulted using a Kibana Dashboard created for the purpose of this project.

To document the REST DSL Api of the REST endpoints managed by Apache Camel, we have used the Camel Swagger Servlet has been configured in order to allow the Swagger UI to get the json stream generated by Camel from the REST DSL syntax parsed within the project. The Servlet can be registered using a web.xml file or when you deploy the project on JBoss Fuse which is an OSGI container by using the Blueprint IoC container and a OSGI HTTP Service

<service interface="javax.servlet.http.HttpServlet">
        <service-properties>
            <entry key="alias" value="/rest/api-docs/*"/>
            <entry key="init-prefix" value="init."/>
            <entry key="init.cors" value="true"/>
            <entry key="init.base.path" value="${swaggerBasePath}"/>
        </service-properties>
        <bean class="org.apache.camel.component.swagger.DefaultCamelSwaggerServlet"/>
    </service>

    <!-- to setup camel servlet with OSGi HttpService -->
    <reference id="httpService" interface="org.osgi.service.http.HttpService"/>

The Service properties fields define the fields to be configured for the Swagger Servlet that Swagger will use to setup the path to access the JSON doc generated and path also to access the endpoint deployed on the server.

You can find the required info about how to configure and use the Camel-Swagger component here. A new component has been created recently within the Apache Camel project as Swagger has refactored its API to use Java as language instead of Scala.