pfx-rest

Summary: Reference for the pfx-rest Camel component — HTTP REST calls to external APIs with connection/authentication support.

Overview

The pfx-rest component is a producer-only Camel component for making HTTP requests to external APIs. It supports all standard HTTP methods, multiple authentication strategies (Basic, OAuth2, JWT, public/no-auth), named connections, proxy configuration, response size limits, streaming, and connection pooling.

The component is registered under the scheme pfx-rest and belongs to the API category.

URI Format

pfx-rest:method[?options]

The method path parameter is required and determines the HTTP method used. It also supports a special system method for system-configuration-based requests.

Supported Methods

Endpoint Parameters

Core Parameters

Input/Output Routing

Proxy

Timeouts

Connection Pooling and Keep-Alive

Streaming and File Upload

Connection Behavior

System Configuration (method=system)

Connection Types

The pfx-rest component supports four connection types, each providing a different authentication strategy:

REST Public (rest-public)

No authentication. Used for accessing public APIs.

• Fields: url, headers

REST Basic (rest-basic)

HTTP Basic authentication. Credentials are sent with every request.

• Fields: url, headers, username, password, authRequestHeader (default: Authorization), authRequestHeaderBearer (default: Basic)

REST JWT (rest-jwt)

Token-based authentication. A token is obtained from an auth endpoint before the first request and refreshed when it expires.

• Fields: url, headers, authUrl, username, password, authRequestTemplate (default: {"username": "::username","password":"::password"}), authRequestContentType (default: application/json), authRequestHeader, authRequestHeaderBearer (default: Bearer), authResponseTokenKey (default: access_token), authResponseExpirationKey (default: expires_in), authResponseExpirationKeyLocation, authExpirationMultiplier (default: 1), reAuthOnCodes

REST OAuth2 (rest-oauth2)

OAuth2 authentication. Similar to JWT but supports client credentials and scope.

• Fields: url, headers, authUrl, username, password, clientId, clientSecret, scope, authRequestTemplate (default: {"grant_type": "password","client_id": "::clientId","client_secret": "::clientSecret","username": "::username","password":"::password"}), authRequestContentType (default: application/x-www-form-urlencoded), authRequestHeader, authRequestHeaderBearer (default: Bearer), authResponseTokenKey, authResponseExpirationKey, authResponseExpirationKeyLocation, authExpirationMultiplier, reAuthOnCodes

Authentication Template Placeholders

Token-based connections (JWT, OAuth2) use authRequestTemplate with these placeholders:

Re-authentication on Error Codes

For token-based connections, the reAuthOnCodes field accepts a comma-separated list of HTTP status codes (e.g., 400,401,404). When any of these codes are returned from a request, the component will re-authenticate and retry. This is useful for systems like Salesforce where tokens may be invalidated unexpectedly.

Usage Examples

GET with named connection

<route id="restGet">
    <from uri="direct:fetchData"/>
    <to uri="pfx-rest:get?connection=myRestConn&amp;uri=/api/v1/products"/>
</route>

POST with inline body

<route id="restPost">
    <from uri="direct:sendData"/>
    <to uri="pfx-rest:post?connection=myRestConn&amp;uri=/api/v1/orders&amp;contentType=application/json"/>
</route>

The exchange body is sent as the request body.

GET with query parameters

Unmatched URI parameters (those not recognized as component options) are automatically collected as query parameters:

<route id="restGetWithParams">
    <from uri="direct:search"/>
    <to uri="pfx-rest:get?connection=myRestConn&amp;uri=/api/v1/search&amp;q=test&amp;limit=100"/>
</route>

Here, q and limit are passed as query parameters: /api/v1/search?q=test&limit=100.

Download large file with streaming

<route id="restDownload">
    <from uri="direct:downloadFile"/>
    <to uri="pfx-rest:get?connection=myRestConn&amp;uri=/api/v1/export&amp;disableStreamCache=true&amp;downloadDir=/tmp/downloads"/>
</route>

Using input/output routing

<route id="restInputOutput">
    <from uri="direct:start"/>
    <setHeader name="requestPayload">
        <constant>{"key": "value"}</constant>
    </setHeader>
    <to uri="pfx-rest:post?connection=myRestConn&amp;uri=/api/v1/data&amp;inputSource=header&amp;inputSourceName=requestPayload&amp;outputTarget=header&amp;outputTargetName=responseData"/>
    <!-- response is now in header 'responseData', body is unchanged -->
</route>

Response size limit

<to uri="pfx-rest:get?connection=myRestConn&amp;uri=/api/v1/large-data&amp;maxResponseSizeInMB=50"/>

An exception is thrown if the response exceeds 50 MB.

Error Handling

• If failIfNoConnection is true and the named connection is not found, the component throws an exception.

• If failIfNoConnection is false (default) and no connection is found, a default no-auth connection is used.

• HTTP responses outside the okStatusCodeRange result in an ExternalSystemException.

• Proxy misconfiguration (only one of proxyHost/proxyPort set) is detected by the proxyValid() check.

See Also

• Connections -- managing REST connections in Integration Manager

• Routes -- route configuration

• Mappers -- request/response mapping

• Filters -- filtering