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`.
`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`.
`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).
`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.
`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.
`retainPayloadOnFailure`	Whether the incoming payload is available for error processing on failure. Defaults to `false`.

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.

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.

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).

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.

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.

retainPayloadOnFailure

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

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.
messageLoggingStrategy	Strategy for describing how a processor’s message is logged on the server.
payloadArchivingStrategy	Strategy for archiving payloads.
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.

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.

messageLoggingStrategy

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

payloadArchivingStrategy

Strategy for archiving payloads.

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.

Details

Responses

The restRequest processor does not perform unmarshalling of responses but returns them as JSON strings that can be unmarshalled with an inboundTransformationStrategy later in the flow if needed. When conversion requires a characterSet config, these character encoding constants are supported. If the payload is to be converted from an object, the conversion format can be specified as JSON, JAXB, or XML.

Encoding for parsing the response is chosen by the following priority:

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

If a failure occurs during processing, a response code within the 400 range will be interpreted as a non-transient failure (i.e., a retry should be attempted). All other failures are considered transient.

Supported Methods

The restRequest processor supports the following HTTP methods:

Method Description

Method	Description
POST PUT PATCH	If the `defaultEntityContentType` is set to `application/x-www-form-urlencoded`, form parameters will be generated based on the properties of the payload. Otherwise, the payload (converted to String format) will be used as the request entity. See the MDN web docs for specifics on form parameter encoding.
GET DELETE	The properties of the payload will be used as query string parameters.

POST
PUT
PATCH

If the defaultEntityContentType is set to application/x-www-form-urlencoded, form parameters will be generated based on the properties of the payload. Otherwise, the payload (converted to String format) will be used as the request entity. See the MDN web docs for specifics on form parameter encoding.

GET
DELETE

The properties of the payload will be used as query string parameters.

POST, PUT and PATCH requests will use the defaultEntityContentType value as the Content-Type header. If not provided, then application/json; charset=UTF-8 will be used. If only the media type is provided (e.g., application/json), the charset will default to UTF-8.

Exchange Properties

Before Processing

Various message exchange properties can be set before the restRequest processor is executed to alter the request that is made. For example, the address could have parameters (enclosed in curly braces) that would be replaced by the corresponding message exchange properties prefixed with requestParameter. The following setup demonstrates how this might work:

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

Message properties prefixed with requestHeader will be converted into HTTP request headers. For example, a property named requestHeader.foobar with a value of baz would result in a request header of foobar: baz.

It’s also possible to override the address, request method, and/or authentication config by setting the exchange properties addressOverride, httpMethodOverride, and authConfKeyOverride respectively. You can use constants ADDRESS_OVERRIDE, HTTP_METHOD_OVERRIDE, and AUTH_CONF_KEY_OVERRIDE to more easily access these names. For example:

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

After Processing

All consumed message properties (addressOverride, httpMethodOverride, authConfKeyOverride, requestHeader.*, requestParameter.*) will be removed after processing and not forwarded to the next processor. The restRequest processor will also filter out any existing responseHeader.* message exchange properties, regardless if the responseHeadersToForward property was configured.

Note that responseHeadersToForward uses a case-insensitive search to find matching headers but will set the exchange property to the case of the configuration and not the actual header. For instance, responseHeadersToForward="foo" might find a header called FOO, but the exchange property becomes responseHeader.foo. However, if the wildcard (*) is used, then the original header is returned 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 could not only remove headers you intended for the restApi flow’s response but could also set headers you didn’t intend for the flow’s response. If the latter is the case, you would need to delete those exchange properties before the response is returned.

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. Thus, if you want the restApi flow to return the same status code as restRequest, you must copy over 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. :imageprefix:

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?