Page History

h2. Restlet Component

The *Restlet* component provides [Restlet|http://www.restlet.org] based [endpoints|Endpoint] for consuming and producing RESTful resources.

Maven users will need to add the following dependency to their {{pom.xml}} for this component:
{code:xml}
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-restlet</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
{code}

h3. URI format

{code}
restlet:restletUrl[?options]
{code}
Format of restletUrl:
{code}
protocol://hostname[:port][/resourcePattern]
{code}
Restlet promotes decoupling of protocol and application concerns.  The reference implementation of [Restlet Engine|http://www.noelios.com/products/restlet-engine] supports a number of protocols.  However, we have tested the HTTP protocol only.  The default port is port 80.  We do not automatically switch default port based on the protocol yet.

You can append query options to the URI in the following format, {{?option=value&option=value&...}}

h3. Options
{div:class=confluenceTableSmall}
|| Name || Default Value || Description ||
| {{headerFilterStrategy=#}}{_}refName_ (*2.x or later*) | An instance of {{RestletHeaderFilterStrategy}} | Use the {{\#}} notation ({{headerFilterStrategy=#}}{_}refName_) to reference a header filter strategy in the Camel Registry.  The strategy will be plugged into the restlet binding if it is {{HeaderFilterStrategyAware}}. |
| {{restletBindingRef}} (*1.x*), \\  {{restletBinding=#}}{_}refName_ (*2.x or later*) | An instance of {{DefaultRestletBinding}} | The bean ID of a {{RestletBinding}} object in the Camel Registry. |
| {{restletMethod}} | {{GET}} | On a producer endpoint, specifies the request method to use.  On a consumer endpoint, specifies that the endpoint consumes only {{restletMethod}} requests.  The string value is converted to [org.restlet.data.Method|http://www.restlet.org/documentation/1.1/api/org/restlet/data/Method.html] by the {{Method.valueOf(String)}} method. |
| {{restletMethods}} (*2.x or later*) | _None_ | *Consumer only* Specify one or more methods separated by commas (e.g. {{restletMethods=post,put}}) to be serviced by a restlet consumer endpoint.  If both {{restletMethod}} and {{restletMethods}} options are specified, the {{restletMethod}} setting is ignored. |
| {{restletRealmRef}} (*1.x*), \\  {{restletRealm=#}}{_}refName_ *(2.x or later)* | {{null}} | The bean ID of the Realm Map in the Camel Registry. |
| {{restletUriPatterns=#}}{_}refName_ (*2.x or later*) | _None_ | *Consumer only* Specify one ore more URI templates to be serviced by a restlet consumer endpoint, using the {{\#}} notation to reference a {{List<String>}} in the Camel Registry.  If a URI pattern has been defined in the endpoint URI, both the URI pattern defined in the endpoint and the {{restletUriPatterns}} option will be honored. |
| {{throwExceptionOnFailure}} (*2.6 or later*)| true | *Producer only * Throws exception on a producer failure. |
{div}

h3. Message Headers

h4. Camel 1.x
{div:class=confluenceTableSmall}
|| Name || Type || Description ||
| {{org.apache.camel.restlet.auth.login}} | {{String}} | Login name for basic authentication.  It is set on the IN message by the application and gets filtered before the restlet request header by Camel. |
| {{org.apache.camel.restlet.auth.password}} | {{String}} | Password name for basic authentication.  It is set on the IN message by the application and gets filtered before the restlet request header by Camel. |
| {{org.apache.camel.restlet.mediaType}} | {{String}} | Specifies the content type, which can be set on the OUT message by the application/processor.  The value is the {{content-type}} of the response message.  If this header is not set, the {{content-type}} is set based on the object type of the OUT message body. |
| {{org.apache.camel.restlet.queryString}} | {{String}} | The query string of the request URI.  It is set on the IN message by {{DefaultRestletBinding}} when the restlet component receives a request. |
| {{org.apache.camel.restlet.responseCode}} | {{String}} or {{Integer}} | The response code can be set on the OUT message by the application/processor.  The value is the response code of the response message.  If this header is not set, the response code is set by the restlet runtime engine. |
| {{org.restlet.\*}} | | Attributes of a restlet message that get propagated to Camel IN headers. |
{div}

h4. Camel 2.x
{div:class=confluenceTableSmall}
|| Name || Type || Description ||
| {{Content-Type}} | {{String}} | Specifies the content type, which can be set on the OUT message by the application/processor.  The value is the {{content-type}} of the response message.  If this header is not set, the content type is based on the object type of the OUT message body. In Camel 2.3 onward, if the Content-Type header is specified in the Camel IN message, the value of the header determine the content type for the Restlet request message.&nbsp;&nbsp; Otherwise, it is defaulted to "application/x-www-form-urlencoded'.  Prior to release 2.3, it is not possible to change the request content type default. |
| {{CamelHttpMethod}} | {{String}} | The HTTP request method.  This is set in the IN message header. |
| {{CamelHttpQuery}} | {{String}} | The query string of the request URI.  It is set on the IN message by {{DefaultRestletBinding}} when the restlet component receives a request. |
| {{CamelHttpResponseCode}} | {{String}} or {{Integer}} | The response code can be set on the OUT message by the application/processor.  The value is the response code of the response message.  If this header is not set, the response code is set by the restlet runtime engine. |
| {{CamelHttpUri}} | {{String}} | The HTTP request URI.  This is set in the IN message header. |
| {{CamelRestletLogin}} | {{String}} | Login name for basic authentication.  It is set on the IN message by the application and gets filtered before the restlet request header by Camel. |
| {{CamelRestletPassword}} | {{String}} | Password name for basic authentication.  It is set on the IN message by the application and gets filtered before the restlet request header by Camel. |
| {{org.restlet.\*}} | | Attributes of a Restlet message that get propagated to Camel IN headers. |
{div}

h3. Message Body

Camel will store the restlet response from the external server on the OUT body. All headers from the IN message will be copied to the OUT message, so that headers are preserved during routing.

h3. Samples

h4. Restlet Endpoint with Authentication

The following route starts a {{restlet}} consumer endpoint that listens for {{POST}} requests on [http://localhost:8080].  The processor creates a response that echoes the request body and the value of the {{id}} header.
{snippet:id=consumer_route|lang=java|url=camel/trunk/components/camel-restlet/src/test/java/org/apache/camel/component/restlet/route/TestRouteBuilder.java}
The {{restletRealm}} setting (in *2.x*, use the {{\#}} notation,  that is, {{restletRealm=#_refName{_}}})in the URI query is used to look up a Realm Map in the registry.  If this option is specified, the restlet consumer uses the information to authenticate user logins.  Only _authenticated_ requests can access the resources.  In this sample, we create a Spring application context that serves as a registry.  The bean ID of the Realm Map should match the _restletRealmRef_.
{snippet:id=realm|lang=xml|url=camel/trunk/components/camel-restlet/src/test/resources/org/apache/camel/component/restlet/camel-context.xml}
The following sample starts a {{direct}} endpoint that sends requests to the server on [http://localhost:8080] (that is, our restlet consumer endpoint).
{snippet:id=producer_route|lang=java|url=camel/trunk/components/camel-restlet/src/test/java/org/apache/camel/component/restlet/route/TestRouteBuilder.java}
That is all we need.  We are ready to send a request and try out the restlet component:

{snippet:id=auth_request|lang=java|url=camel/trunk/components/camel-restlet/src/test/java/org/apache/camel/component/restlet/RestletRouteBuilderAuthTest.java}

The sample client sends a request to the {{direct:start-auth}} endpoint with the following headers:
* {{CamelRestletLogin}} (used internally by Camel)
* {{CamelRestletPassword}} (used internally by Camel)
* {{id}} (application header)

{info:title=Note}
{{org.apache.camel.restlet.auth.login}} and {{org.apache.camel.restlet.auth.password}} will not be propagated as Restlet header.
{info}

The sample client gets a response like the following:
{code}
received [<order foo='1'/>] as an order id = 89531
{code}

h4. Single restlet endpoint to service multiple methods and URI templates (2.0 or later)

It is possible to create a single route to service multiple HTTP methods using the {{restletMethods}} option.  This snippet also shows how to retrieve the request method from the header:
{snippet:id=routeDefinition|lang=java|url=camel/trunk/components/camel-restlet/src/test/java/org/apache/camel/component/restlet/RestletMultiMethodsEndpointTest.java}

In addition to servicing multiple methods, the next snippet shows how to create an endpoint that supports multiple URI templates using the {{restletUriPatterns}} option.  The request URI is available in the header of the IN message as well.  If a URI pattern has been defined in the endpoint URI (which is not the case in this sample), both the URI pattern defined in the endpoint and the {{restletUriPatterns}} option will be honored.

{snippet:id=routeDefinition|lang=java|url=camel/trunk/components/camel-restlet/src/test/java/org/apache/camel/component/restlet/RestletMultiUriTemplatesEndpointTest.java}

The {{restletUriPatterns=#uriTemplates}} option references the {{List<String>}} bean defined in the Spring XML configuration.

{code:xml}
<util:list id="uriTemplates">
    <value>/users/{username}</value>
    <value>/atom/collection/{id}/component/{cid}</value>
</util:list>
{code}