REST Services (Dev Guides)

Apache Camel does support multiple approaches to defining and using REST services. In particular, Apache Camel provides a REST DSL (Domain Specific Language), which is a simple but powerful fluent API that can be layered over any REST component and provides integration with Swagger.

Overview

Apache Camel provides many different approaches and components for defining REST services in your Camel applications. In this content, we will provide a quick overview of these approaches and components, to allow you to decide which implementation and API best fit your requirements.

What is REST?

Representational State Transfer (REST) is an architecture for distributed applications that centers around the transmission of data over HTTP, using only the four basic HTTP verbs: GET, POST, PUT, and DELETE.

In contrast to a protocol such as SOAP, which treats HTTP as a mere transport protocol for SOAP messages, the REST architecture exploits HTTP directly. The core insight is that the HTTP protocol itself, augmented by a few simple conventions, is eminently suitable to serve as the framework for distributed applications.

REST Invocation

Because the REST architecture is built around standard HTTP, in many cases you can use a regular browser as a REST client. For example, to invoke a simple Hello World REST service running on the host and port, localhost:9091, you could navigate to a URL like the following in your browser:

http://localhost:9091/say/hello/Jane

REST Wrappers

These REST wrapper layers offer a simplified syntax for defining REST services and can be layered on top of different REST implementations:

REST DSL

The REST DSL (in camel-core) is a facade or wrapper layer that provides a simplified builder API for defining REST services. The REST DSL does not itself provide a REST implementation: it must be combined with an underlying REST implementation. For example, the following Java code shows how to define a simple Hello World service using the REST DSL:

rest("/say")
    .get("/hello/{name}").route().transform().simple("Hello ${header.name}");

REST Component

The REST component (in camel-core) is a wrapper layer that enables you to define REST services using a URI syntax. Just like the REST DSL, it does not itself provide a REST implementation. Therefore, it must be combined with an underlying REST implementation.

The following code shows how to define a simple Hello World service using the camel-rest component:

from("rest:get:say:/hello/{name}").transform().simple("Hello ${header.name}");

Restlet Component

This component (in camel-restlet) is a REST implementation that can be layered above different transport protocols (although it is only tested against the HTTP protocol). This component also provides an integration with the Restlet Framework (a commercial framework for developing REST services in Java).

For example, the following code shows how to define a simple Hello World service using the Restlet component:

JAX-RS REST implementation

JAX-RS (Java API for RESTful Web Services) is a framework for binding REST requests to Java objects, where the Java classes must be decorated with JAX-RS annotations in order to define the binding. The JAX-RS framework is relatively mature and provides a sophisticated framework for developing REST services.

The JAX-RS integration with Apache Camel is implemented by the CXFRS component, it is layered over Apache CXF. Thus, JAX-RS binds a REST request to a Java class using the following annotations:

@Path

Annotation that can map a context path to a Java class or map a sub-path to a particular Java method.

@GET, @POST, @PUT, @DELETE

Annotations that map an HTTP method to a Java method.

@PathParam

Annotation that can either map a URI parameter to a Java method argument or injects a URI parameter into a field.

@QueryParam

Annotation that can either map a query parameter to a Java method argument or injects a query parameter into a field.