restRequest

Processor that produces a message from a REST endpoint.

Properties

Name Summary

Name	Summary
`address`	URL of the REST service to call. Required.
`defaultMethod`	The `HttpMethod` that will be used for the request. Optional and defaults to `GET`.
`defaultEntityContentType`	Optional `Content-Type` header for the request. Consists of the media type of the entity-body that is being sent (for methods that have entities, such as `POST` and `PUT`). The header should be provided on the format `<media type>; charset=<charset>`. The charset is optional and defaults to `UTF-8`.
`processEntityAsText`	Optional. When set to true, the entity will be converted to a string, regardless of `Content-Type`
`defaultAcceptedContentType`	Optional default value for the `Content-Type` of the response, if the response does not contain its own `Content-Type` header. Consists of the media type of the entity-body that is being sent (for methods that have entities, such as `POST` and `PUT`). The header should be provided on the format: `<media type>; charset=<charset>`. The charset is optional and defaults to `UTF-8`.
`processResponseBodyAsText`	Optional. When set to true, the response body (if present) will be converted to a string, regardless of `Content-Type`
`authenticationConfigKey`	Secrets key used to look up credentials to append to the request (e.g., as an authorization header). Also supports a comma separated list of Secrets keys, if multiple authentication methods are required on the same request. Optional.
`responseHeadersToForward`	Optional, comma separated list of response headers to forward. Wildcard `` can be used when all response headers are to be forwarded. Response headers are available downstream as exchange properties prepended with `responseHeader.` (e.g., `responseHeader.myHeader`). All existing `responseHeader.` prefixed exchange properties will be filtered out, even if forwarding of request headers is not configured. Thus, any `responseHeader.` exchange properties on the message exchange will always represent the response headers of the latest `restRequest`. When forwarding headers, the casing of the selection configurations is used, not the casing of the actual header names. The `responseHeader.` prefix is also used by the `restApi` source to add additional headers to the response, so any `responseHeader.*` headers selected can ultimately end up being used as response headers of an upstream `restApi` source. If this is not desired, the flow must actively delete the exchange properties before the response is returned.
`nonFailureResponseStatuses`	Optional, comma separated list of response status codes or response status code ranges that will not result in message failure. When a non-success status is returned, and the status is found in the list of non-failure statuses, the response entity is set as the payload. Can be configured with error status codes from client (4xx), server (5xx) error status families, and 304 (Not Modified). Examples: "400, 304": Status codes 400 and 304 "400-499": Status codes between 400 and 499, including 400 and 499 "400-499, 500": Status codes between 400-499 inclusive and 500
`transientFailureResponseStatuses`	Optional, comma separated list of response status codes or response status code ranges that will be treated as transient errors. When a non-transient status is returned but the status is found in the list of transient failure statuses then redelivery will be attempted. Can be configured with error status codes from client (4xx) error status families. Examples: "400, 404": Status codes 400 and 404 "400-499": Status codes between 400 and 499, including 400 and 499 "400-405, 410": Status codes between 400-405 inclusive and 410
`retainStatusCode`	Whether the response status code is to be stored as an exchange property under the key `responseStatusCode`. Any existing `responseStatusCode` exchange properties will be removed before processing, even if this `restRequest` is not configured to forward the status. Thus, any `responseStatusCode` exchange properties on the message exchange will always represent the response status of the latest `restRequest`. Optional.
`connectionTimeoutMillis`	Connection timeout value. Optional.
`receiveTimeoutMillis`	Socket timeout value. Optional.
`proxyHost`	Hostname of the proxy server to use. Optional.
`proxyPort`	Port of the proxy server to use. Optional.
`proxyAuthenticationConfigKey`	Key from the server configuration used to look up proxy credentials to append to the request. Optional.
`sslAuthenticationConfigKey`	Optional key from the server configuration used to look up SSL credentials for server and client authentication.
`httpVersionPolicy`	Optional `HttpVersionPolicy` defining how to select the HTTP version, either by negotiation or by enforcing HTTP/1 or 2.
`payloadPropertiesAsQueryParametersStrategy`	Optional `PayloadPropertiesAsQueryParameterStrategy` defining which type of outgoing requests that will use payload properties as query parameters. Default behaviour is GET_AND_DELETE.
`retainPayloadOnFailure`	Whether the incoming payload is available for error processing on failure. Defaults to `false`.
`name`	Optional, descriptive name for the processor.
`id`	Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern `[a-zA-Z][a-zA-Z0-9_-]{2,29}`.
`exchangeProperties`	Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.

address

URL of the REST service to call. Required.

defaultMethod

The HttpMethod that will be used for the request. Optional and defaults to GET.

defaultEntityContentType

Optional Content-Type header for the request. Consists of the media type of the entity-body that is being sent (for methods that have entities, such as POST and PUT). The header should be provided on the format <media type>; charset=<charset>. The charset is optional and defaults to UTF-8.

processEntityAsText

Optional. When set to true, the entity will be converted to a string, regardless of Content-Type

defaultAcceptedContentType

Optional default value for the Content-Type of the response, if the response does not contain its own Content-Type header. Consists of the media type of the entity-body that is being sent (for methods that have entities, such as POST and PUT). The header should be provided on the format: <media type>; charset=<charset>. The charset is optional and defaults to UTF-8.

processResponseBodyAsText

Optional. When set to true, the response body (if present) will be converted to a string, regardless of Content-Type

authenticationConfigKey

Secrets key used to look up credentials to append to the request (e.g., as an authorization header). Also supports a comma separated list of Secrets keys, if multiple authentication methods are required on the same request. Optional.

responseHeadersToForward

Optional, comma separated list of response headers to forward. Wildcard * can be used when all response headers are to be forwarded. Response headers are available downstream as exchange properties prepended with responseHeader. (e.g., responseHeader.myHeader). All existing responseHeader. prefixed exchange properties will be filtered out, even if forwarding of request headers is not configured. Thus, any responseHeader.* exchange properties on the message exchange will always represent the response headers of the latest restRequest.

When forwarding headers, the casing of the selection configurations is used, not the casing of the actual header names. The responseHeader. prefix is also used by the restApi source to add additional headers to the response, so any responseHeader.* headers selected can ultimately end up being used as response headers of an upstream restApi source. If this is not desired, the flow must actively delete the exchange properties before the response is returned.

nonFailureResponseStatuses

Optional, comma separated list of response status codes or response status code ranges that will not result in message failure. When a non-success status is returned, and the status is found in the list of non-failure statuses, the response entity is set as the payload. Can be configured with error status codes from client (4xx), server (5xx) error status families, and 304 (Not Modified).

Examples: "400, 304": Status codes 400 and 304 "400-499": Status codes between 400 and 499, including 400 and 499 "400-499, 500": Status codes between 400-499 inclusive and 500

transientFailureResponseStatuses

Optional, comma separated list of response status codes or response status code ranges that will be treated as transient errors. When a non-transient status is returned but the status is found in the list of transient failure statuses then redelivery will be attempted. Can be configured with error status codes from client (4xx) error status families.

Examples: "400, 404": Status codes 400 and 404 "400-499": Status codes between 400 and 499, including 400 and 499 "400-405, 410": Status codes between 400-405 inclusive and 410

retainStatusCode

Whether the response status code is to be stored as an exchange property under the key responseStatusCode. Any existing responseStatusCode exchange properties will be removed before processing, even if this restRequest is not configured to forward the status. Thus, any responseStatusCode exchange properties on the message exchange will always represent the response status of the latest restRequest. Optional.

connectionTimeoutMillis

Connection timeout value. Optional.

receiveTimeoutMillis

Socket timeout value. Optional.

proxyHost

Hostname of the proxy server to use. Optional.

proxyPort

Port of the proxy server to use. Optional.

proxyAuthenticationConfigKey

Key from the server configuration used to look up proxy credentials to append to the request. Optional.

sslAuthenticationConfigKey

Optional key from the server configuration used to look up SSL credentials for server and client authentication.

httpVersionPolicy

Optional HttpVersionPolicy defining how to select the HTTP version, either by negotiation or by enforcing HTTP/1 or 2.

payloadPropertiesAsQueryParametersStrategy

Optional PayloadPropertiesAsQueryParameterStrategy defining which type of outgoing requests that will use payload properties as query parameters. Default behaviour is GET_AND_DELETE.

retainPayloadOnFailure

Whether the incoming payload is available for error processing on failure. Defaults to false.

name

Optional, descriptive name for the processor.

id

Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern [a-zA-Z][a-zA-Z0-9_-]{2,29}.

exchangeProperties

Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.

Sub-builders

Name	Summary
processingStrategy	Strategy for providing message processing hints to the server. Optional.
externalSystemDetails	Strategy for describing the external system integration. Optional.
circuitBreakerStrategy	Strategy for configuring the processor’s circuit breaker. Optional.
inboundTransformationStrategy	Strategy that customizes the conversion of an incoming payload by a processor (e.g., string to object). Should be used when the processor’s default conversion logic cannot be used.
messageLoggingStrategy	Strategy for describing how a processor’s message is logged on the server.
payloadArchivingStrategy	Strategy for archiving payloads.

Name

Summary

processingStrategy

Strategy for providing message processing hints to the server. Optional.

externalSystemDetails

Strategy for describing the external system integration. Optional.

circuitBreakerStrategy

Strategy for configuring the processor’s circuit breaker. Optional.

inboundTransformationStrategy

Strategy that customizes the conversion of an incoming payload by a processor (e.g., string to object). Should be used when the processor’s default conversion logic cannot be used.

messageLoggingStrategy

Strategy for describing how a processor’s message is logged on the server.

payloadArchivingStrategy

Strategy for archiving payloads.

Details

Content Type Interpretation

The restRequest processor classifies MIME types as text-based or binary for request entities and responses. It uses this classification to decide whether to convert payloads and response bodies to strings or handle them as binary data.

Text-Based Content Types

application/xml
application/json
application/javascript
MIME types that start with text/
MIME types that end with +xml or +json

Binary Content Types

All content types that are not text-based are treated as binary, such as application/octet-stream.

Multipart Form Data Requests

The restRequest processor supports multipart form data requests when defaultEntityContentType is set to multipart/form-data. In this case, it validates the payload against the following schema:

Field Type Required Description

Field	Type	Required	Description
`parts`	array	Yes	List of multipart body parts
`parts[].name`	string	Yes	The name of the part (e.g., `file`, `metadata`)
`parts[].contentType`	string	Yes	MIME type of the part (e.g., `application/octet-stream`, `application/json`)
`parts[].content`	string	Yes	The content of the part; Base64-encoded for binary data and a raw string for text-based MIME types
`parts[].filename`	string	No	Optional filename; used when the part represents a file (e.g., `hello.bin`). Omitted for non-file parts.

parts

array

Yes

List of multipart body parts

parts[].name

string

Yes

The name of the part (e.g., file, metadata)

parts[].contentType

string

Yes

MIME type of the part (e.g., application/octet-stream, application/json)

parts[].content

string

Yes

The content of the part; Base64-encoded for binary data and a raw string for text-based MIME types

parts[].filename

string

Optional filename; used when the part represents a file (e.g., hello.bin). Omitted for non-file parts.

Example multipart form data payload:

{
  "parts": [
    {
      "name": "file",
      "contentType": "application/octet-stream",
      "content": "aGVsbG8gd29ybGQ=",
      "filename": "hello.bin"
    },
    {
      "name": "metadata",
      "contentType": "application/json",
      "content": "{\"key\": \"value\"}"
    }
  ]
}

Responses

The restRequest processor does not unmarshal responses. It returns responses as string or binary. If needed, you can unmarshal the response later in the flow by using an inboundTransformationStrategy. If conversion requires a characterSet configuration, use one of these character encoding constants. If you convert the payload from an object, you can set the conversion format to JSON, JAXB, or XML.

Requests that fail with a 4xx (client error) status code are treated as non-transient failures, and these messages are not redelivered. All other failures are treated as transient and trigger message redelivery.

Text-Based Responses

The restRequest processor returns string if any of the following conditions are true:

processResponseBodyAsText configuration is set to true, regardless of the Content-Type response header.
The Content-Type response header is set to a text-based type.
The Content-Type response header is not present and defaultAcceptedContentType is set to one of the text-based types.

The processor chooses the encoding for parsing the response in this order:

The charset from the Content-Type response header
The charset from the defaultAcceptedContentType config parameter
UTF-8 for MIME type JSON
The charset from the defaultEntityContentType config parameter
ISO_8859_1 otherwise

Binary Responses

If the Content-Type response header value is interpreted as a binary content type, the restRequest processor returns binary unless processResponseBodyAsText is set to true.

Supported Methods

The restRequest processor supports the following HTTP methods:

Method Description

Method	Description
POST PUT PATCH	If `defaultEntityContentType` is set to `multipart/form-data`, the payload must be structured as described in the Multipart Form Data Requests section above. If `defaultEntityContentType` is set to `application/x-www-form-urlencoded`, the processor generates form parameters from payload properties. Otherwise, the processor uses the payload as the request entity. It converts the payload to string or treats it as binary based on `defaultEntityContentType` and `processEntityAsText`. If `processEntityAsText` is set to `true`, the processor always converts the entity to string, regardless of `defaultEntityContentType`. If `processEntityAsText` is `false`, the processor converts text-based content types to string and treats all other content types as binary. See the MDN web docs for specifics on form parameter encoding.
GET DELETE	The processor uses payload properties as query string parameters based on the `PayloadPropertiesAsQueryParameterStrategy` setting. The default is `GET_AND_DELETE`. For more information, see Payload Properties as Query Parameters.

POST
PUT
PATCH

If defaultEntityContentType is set to multipart/form-data, the payload must be structured as described in the Multipart Form Data Requests section above.

If defaultEntityContentType is set to application/x-www-form-urlencoded, the processor generates form parameters from payload properties.

Otherwise, the processor uses the payload as the request entity. It converts the payload to string or treats it as binary based on defaultEntityContentType and processEntityAsText. If processEntityAsText is set to true, the processor always converts the entity to string, regardless of defaultEntityContentType. If processEntityAsText is false, the processor converts text-based content types to string and treats all other content types as binary.

See the MDN web docs for specifics on form parameter encoding.

GET
DELETE

The processor uses payload properties as query string parameters based on the PayloadPropertiesAsQueryParameterStrategy setting. The default is GET_AND_DELETE. For more information, see Payload Properties as Query Parameters.

POST, PUT, and PATCH requests use the defaultEntityContentType value as the Content-Type header. If you do not provide a value, the processor uses application/json; charset=UTF-8. If only the media type is provided (e.g., application/json), the charset will default to UTF-8 for text-based types.

Multipart form data requests use multipart/form-data for the Content-Type header and include an automatically generated boundary identifier.

Payload Properties as Query Parameters

The PayloadPropertiesAsQueryParameterStrategy enum controls how payload properties are handled as query parameters for GET and DELETE requests:

GET_AND_DELETE: Properties are used as query parameters for both GET and DELETE requests.
GET: Properties are used as query parameters only for GET requests.
DELETE: Properties are used as query parameters only for DELETE requests.
NONE: Payload properties are not included as query parameters for any requests.

Exchange Properties

Before Processing

You can set message exchange properties before the restRequest processor runs to modify the request. For example, the address can include parameters (in curly braces) that the processor replaces with matching message exchange properties prefixed with requestParameter. The following setup shows how this works:

exchangeProperties="requestParameter.param1=api"
address = URL("https://example.org/path/{param1}/")

Message properties prefixed with requestHeader are converted into HTTP request headers. For example, a property named requestHeader.foobar with a value of baz creates this request header: foobar: baz.

You can also override the address, request method, authentication configuration, and SSL authentication configuration by setting addressOverride, httpMethodOverride, authConfKeyOverride, and sslAuthConfKeyOverride, respectively. To reference these names more easily, use the constants ADDRESS_OVERRIDE, HTTP_METHOD_OVERRIDE, AUTH_CONF_KEY_OVERRIDE, and SSL_AUTH_CONF_KEY_OVERRIDE. For example:

setExchangeProperty {
    id = "set-address-property"
    propertyName = ADDRESS_OVERRIDE
    source = "envelope.payload.header.replyAddress"
}

After Processing

After processing, the processor removes all consumed message properties (addressOverride, httpMethodOverride, authConfKeyOverride, sslAuthConfKeyOverride, requestHeader.*, requestParameter.*) and does not forward them to the next processor. The restRequest processor also filters out existing responseHeader.* message exchange properties, regardless of whether responseHeadersToForward is configured.

responseHeadersToForward uses a case-insensitive search to find matching headers, but it sets the exchange property using the case from the configuration, not from the actual header. For instance, responseHeadersToForward="foo" might find a header called FOO, but the exchange property becomes responseHeader.foo. However, if you use the wildcard (*), the processor returns the original header as responseHeader.FOO.

The restApi source processor uses the same responseHeader.* exchange properties to affect the final response that is returned for that flow. Keep in mind that restRequest can remove headers you intended to return from the restApi flow, and it can also set headers you did not intend to return. If this happens, delete those exchange properties before the flow returns the response.

If the retainStatusCode property is set to true, a responseStatusCode message exchange property is created. Unlike the responseHeader.* exchange properties, there is no overlap with the restApi processor. A flow with a restApi source uses a separate httpResponseCode exchange property to override the status code for its response. If you want the restApi flow to return the same status code as restRequest, copy the value from responseStatusCode to httpResponseCode. For example:

setExchangeProperty {
    id = "set-status"
    propertyName = "httpResponseCode"
    source = "exchangePropertiesMap['responseStatusCode']"
}

Authentication

The authenticationConfigKey property supports secrets of the following types:

See the Secret Types documentation for formatting details of each type.

TLS (SSL) Configuration

Requests can be sent to third-party web services using HTTPS protocol.

If the target service is using a valid SSL certificate, signed by a trusted CA, there is no need for additional configuration. However, configuration must be provided if you require one of the following features:

Providing a client certificate (if requested by the server).
Providing a truststore for server certificate validation. This is useful, for example, when the root certificate has not been signed by a trusted CA.
Limiting the server certificate to a specified public key.
Accepting a self-signed server certificate.
Accepting a server certificate issued for a host other than the one being requested.

To enable these features, the sslAuthenticationConfigKey property must be set and point to a secret of type Tls. See the Secret Types documentation for formatting details.

Was this page helpful?