String
HTTP Connector Reference - Mule 4
HTTP Connector v1.7
Use Anypoint Connector for HTTP (HTTP Connector) to handle and perform HTTP requests. This class
only serves as an extension definition. This
connector’s configurations are divided between a server (<http:listener-config>
) and a client (<http:requester-config>
). capabilities.
Release Notes: HTTP Connector Release Notes
Configurations
Listener Configuration
Configuration element for a HttpListener.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Name |
The name for this configuration. Connectors reference the configuration with this name. |
x |
||
Connection |
The connection types that can be provided to this configuration. |
x |
||
Base Path |
String |
Base path to use for all requests that reference this config. |
||
Listener Interceptors |
Listener interceptors that will apply on request and on response events. |
|||
Reject Invalid Transfer Encoding |
Boolean |
If |
false |
Connection Types
Listener
Connection provider for a HttpListener, handles the creation of HttpServer instances.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
TLS Configuration |
Reference to a TLS config element. This will enable HTTPS for this config. |
|||
Protocol |
Enumeration, one of:
|
Protocol to use for communication. Valid values are HTTP and HTTPS. Default value is HTTP. When using HTTPS the HTTP communication is going to be secured using TLS / SSL. If HTTPS was configured as protocol then the user needs to configure at least the keystore in the tls:context child element of this listener-config. |
HTTP |
|
Host |
String |
Host where the requests will be sent. |
x |
|
Port |
Number |
Port where the requests will be received. |
x |
|
Use Persistent Connections |
Boolean |
If false, each connection will be closed after the first request is completed. |
true |
|
Connection Idle Timeout |
Number |
The number of milliseconds that a connection can remain idle before it is closed. The value of this attribute is only used when persistent connections are enabled. The listener default timeout is bigger than the requester default timeout to avoid the Remotely closed exception when you send a request on an existing connection just before the timeout occurs. |
40000 |
|
Read Timeout |
Number |
Maximum time in milliseconds that the listener must wait while receiving a message. |
30000 |
|
Reconnection |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy |
Associated Sources
Request Configuration
Configuration element for a HTTP requests.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Name |
String |
The name for this configuration. Connectors reference the configuration with this name. |
x |
|
Connection |
The connection types that can be provided to this configuration. |
x |
||
Expiration Policy |
Configures the minimum amount of time that a dynamic configuration instance can remain idle before the runtime considers it eligible for expiration. This does not mean that the platform will expire the instance at the exact moment that it becomes eligible. The runtime will actually purge the instances when it sees it fit. |
|||
Base Path |
String |
Base path to use for all requests that reference this config. |
/ |
|
Follow Redirects |
Boolean |
Specifies whether to follow redirects or not. Default value is true. |
true |
|
Send Body Mode |
Enumeration, one of:
|
Defines if the request should contain a body or not. If AUTO, it will depend on the method (GET, HEAD and OPTIONS will not send a body). |
AUTO |
|
Request Streaming Mode |
Enumeration, one of:
|
Defines if the request should be sent using streaming or not. If this attribute is not present, the behavior will depend on the type of the payload (it will stream only for InputStream). If set to true, it will always stream. If set to false, it will never stream. As streaming is done the request will be sent user Transfer-Encoding: chunked. |
AUTO |
|
Enable Cookies |
Boolean |
If true, cookies received in HTTP responses will be stored, and sent in subsequent HTTP requests. |
true |
|
Default Headers |
Array of Default Header |
Default HTTP headers the message should include. |
||
Query Parameters |
Array of Query Param |
Default Query parameters the request should include. |
||
Send Correlation Id |
Enumeration, one of:
|
Whether to specify a correlation id when publishing messages. This applies both for custom correlation ids specified at the operation level and for default correlation ids taken from the current event. |
AUTO |
|
Preserve Headers Case |
Boolean |
By default, header keys are stored internally in lower-case. This is to improve performance of headers handling and is functionally correct as specified in the RFC. <p> In the case a server expects headers in a specific case, this flag may be set to true so the case of the header keys are preserved. |
false |
|
Response Timeout |
Number |
Maximum time in milliseconds that the request element blocks the execution of the flow waiting for the HTTP response. If this value is not present, the connector uses the default response timeout from the Mule configuration, which is also 10000 |
10000 |
|
Response Validator |
Configures a default error handling of the response. |
Connection Types
Request
Connection provider for a HTTP request, handles the creation of HttpExtensionClient instances.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Proxy Config |
One of: |
Reusable configuration element for outbound connections through a proxy. A proxy element must define a host name and a port attributes, and optionally can define a username and a password. |
||
Authentication |
Authentication method to use for the HTTP request. |
|||
TLS Configuration |
Reference to a TLS config element. This will enable HTTPS for this config. |
|||
Protocol |
Enumeration, one of:
|
Protocol to use for communication. Valid values are HTTP and HTTPS. Default value is HTTP. When using HTTPS the HTTP communication is going to be secured using TLS/SSL. If HTTPS was configured as protocol, then the user can customize the TLS/SSL configuration by defining the |
HTTP |
|
Host |
String |
Host where the requests will be sent. |
||
Port |
Number |
Port where the requests will be sent. If the protocol attribute is HTTP (default) then the default value is 80, if the protocol attribute is HTTPS then the default value is 443. |
||
Use Persistent Connections |
Boolean |
If false, each connection will be closed after the first request is completed. |
true |
|
Max Connections |
Number |
The maximum number of outbound connections that will be kept open at the same time. By default the number of connections is unlimited. |
-1 |
|
Connection Idle Timeout |
Number |
The number of milliseconds that a connection can remain idle before it is closed. The value of this attribute is only used when persistent connections are enabled. |
30000 |
|
Stream Response |
Boolean |
Whether or not received responses should be streamed, meaning processing will continue as soon as all headers are parsed and the body streamed as it arrives. When enabled, the response MUST be eventually read since depending on the configured buffer size it may not fit into memory and processing will stop until space is available. |
false |
|
Response Buffer Size |
Number |
The space in bytes for the buffer where the HTTP response will be stored. |
1024 |
|
Client Socket Properties |
||||
Reconnection |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy |
Operations
Request
<http:request>
Consumes an HTTP service.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Configuration |
String |
The name of the configuration to use. |
x |
|
Method |
String |
The HTTP method for the request. |
GET |
|
Streaming Strategy |
|
Configure if repeatable streams should be used and their behavior |
||
Path |
String |
Path where the request will be sent. |
||
URL |
String |
URL where to send the request. |
||
Follow Redirects |
Boolean |
Specifies whether to follow redirects or not. |
||
Send Body Mode |
Enumeration, one of:
|
Defines if the request should contain a body or not. |
||
Request Streaming Mode |
Enumeration, one of:
|
Defines if the request should be sent using streaming or not. |
||
Response Timeout |
Number |
Maximum time that the request element will block the execution of the flow waiting for the HTTP response. |
||
Body |
Any |
The body of the response message |
#[payload] |
|
Headers |
Object |
HTTP headers the message should include. |
||
URI Parameters |
Object |
URI parameters that should be used to create the request. |
||
Query Parameters |
Object |
Query parameters the request should include. |
||
Send Correlation Id |
Enumeration, one of:
|
Options on whether to include an outbound correlation ID or not |
||
Correlation Id |
String |
Allows you to set a custom correlation ID. |
||
Response Validator |
Configures error handling of the response. |
|||
Target Variable |
String |
The name of a variable on which the operation’s output will be placed |
||
Target Value |
String |
An expression that will be evaluated against the operation’s output and the outcome of that expression will be stored in the target variable |
#[payload] |
|
Reconnection Strategy |
A retry strategy in case of connectivity errors. This field is not used by this operation. |
|||
Output Mime Type |
String |
MIME type of the payload that this operation outputs. |
||
Output Encoding |
String |
Encoding of the payload that this operation outputs. |
Throws
-
HTTP:BAD_REQUEST
-
HTTP:CLIENT_SECURITY
-
HTTP:CONNECTIVITY
-
HTTP:FORBIDDEN
-
HTTP:INTERNAL_SERVER_ERROR
-
HTTP:METHOD_NOT_ALLOWED
-
HTTP:NOT_ACCEPTABLE
-
HTTP:NOT_FOUND
-
HTTP:PARSING
-
HTTP:RETRY_EXHAUSTED
-
HTTP:SECURITY
-
HTTP:SERVICE_UNAVAILABLE
-
HTTP:TIMEOUT
-
HTTP:TOO_MANY_REQUESTS
-
HTTP:UNAUTHORIZED
-
HTTP:UNSUPPORTED_MEDIA_TYPE
-
HTTP:BAD_GATEWAY
-
HTTP:GATEWAY_TIMEOUT
Basic Security Filter
<http:basic-security-filter>
Authenticates received HTTP requests. Must be used after a listener component.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Realm |
String |
Authentication realm. |
x |
|
Security Providers |
Array of String |
The delegate-security-provider to use for authenticating. Use this in case you have multiple security managers defined in your configuration. |
||
Attributes |
The HttpRequestAttributes coming from an HTTP listener source to check the |
#[attributes] |
Load Static Resource
<http:load-static-resource>
Serves up static content for use with HTTP, using the request path to lookup the resource.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Resource Base Path |
String |
The resource base from where documents are served up. For example: /Users/maxthemule/resources |
x |
|
Default File |
String |
The default file to serve when a directory is specified. The default value is |
index.html |
|
Attributes |
The HttpRequestAttributes coming from an HTTP listener source to check the required resources. |
#[attributes] |
||
Target Variable |
String |
The name of a variable on which the operation’s output will be placed |
||
Target Value |
String |
An expression that will be evaluated against the operation’s output and the outcome of that expression will be stored in the target variable |
#[payload] |
Sources
Listener
<http:listener>
Represents a listener for HTTP requests.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Configuration |
String |
The name of the configuration to use. |
x |
|
Path |
String |
Relative path from the path set in the HTTP Listener configuration |
x |
|
Allowed Methods |
String |
Comma separated list of allowed HTTP methods by this listener. To allow all methods do not defined the attribute. |
||
Response Streaming Mode |
Enumeration, one of:
|
Defines if the response should be sent using streaming or not. If this attribute is not present, the behavior will depend on the type of the payload (it will stream only for InputStream). If set to true, it will always stream. If set to false, it will never stream. As streaming is done the response will be sent user Transfer-Encoding: chunked. |
AUTO |
|
Primary Node Only |
Boolean |
Whether this source should only be executed on the primary node when running in Cluster |
||
Streaming Strategy |
|
Configure if repeatable streams should be used and their behavior |
||
Redelivery Policy |
Defines a policy for processing the redelivery of the same message |
|||
Reconnection Strategy |
A retry strategy in case of connectivity errors |
|||
Body |
Any |
The body of the response message. |
#[payload] |
|
Headers |
Object |
HTTP headers the message should include. |
||
Status Code |
Number |
HTTP status code the response should have. |
||
Reason Phrase |
String |
HTTP reason phrase the response should have. |
Types
TLS
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Enabled Protocols |
String |
A comma separated list of protocols enabled for this context. |
||
Enabled Cipher Suites |
String |
A comma separated list of cipher suites enabled for this context. |
||
Trust Store |
||||
Key Store |
||||
Revocation Check |
Trust Store
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Path |
String |
The location (which will be resolved relative to the current classpath and file system, if possible) of the trust store. |
||
Password |
String |
The password used to protect the trust store. |
||
Type |
String |
The type of store used. |
||
Algorithm |
String |
The algorithm used by the trust store. |
||
Insecure |
Boolean |
If true, no certificate validations are performed, rendering connections vulnerable to attacks. Use at your own risk. |
Key Store
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Path |
String |
The location (which resolves relative to the current classpath and file system, if possible) of the key store. |
||
Type |
String |
The type of store used. |
||
Alias |
String |
When the key store contains many private keys, this attribute indicates the alias of the key that should be used. If not defined, the first key in the file is used by default. |
||
Key Password |
String |
The password used to protect the private key. |
||
Password |
String |
The password used to protect the key store. |
||
Algorithm |
String |
The algorithm used by the key store. |
Standard Revocation Check
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Only End Entities |
Boolean |
Only verify the last element of the certificate chain. |
||
Prefer Crls |
Boolean |
Try CRL instead of OCSP first. |
||
No Fallback |
Boolean |
Do not use the secondary checking method (the one not selected before). |
||
Soft Fail |
Boolean |
Avoid verification failure when the revocation server can not be reached or is busy. |
Custom Ocsp Responder
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Url |
String |
The URL of the OCSP responder. |
||
Cert Alias |
String |
Alias of the signing certificate for the OCSP response (must be in the trust store), if present. |
Reconnection
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Fails Deployment |
Boolean |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy |
||
Reconnection Strategy |
The reconnection strategy to use |
Reconnect
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Frequency |
Number |
How often in milliseconds to reconnect. |
||
Count |
Number |
How many reconnection attempts to make. |
||
blocking |
Boolean |
If false, the reconnection strategy runs in a separate, non-blocking thread. |
true |
Reconnect Forever
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Frequency |
Number |
How often in milliseconds to reconnect. |
||
blocking |
Boolean |
If false, the reconnection strategy runs in a separate, non-blocking thread. |
true |
CORS Interceptor Wrapper
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Cors Interceptor |
Interceptor which validates that requests match CORS specification and acts on responses accordingly. |
x |
CORS Listener Interceptor
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Allow Credentials |
Boolean |
false |
||
Origins |
Array of One of:
|
x |
HTTP Request Attributes
To get familiar on how to use message attributes, refer to the about message attributes documentation.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Listener Path |
String |
Full path where the request was received. |
x |
|
Raw Request Path |
String |
Full path requested, encoded as received. @since 1.5.0 |
x |
|
Relative Path |
String |
Path where the request was received, without considering the base path. |
x |
|
Masked Request Path |
String |
Path computed from masking the listenerPath and taking the difference. Note that this is only calculated when the null otherwise. @since 1.4.0 |
x |
|
Version |
String |
HTTP version of the request. |
x |
|
Scheme |
String |
HTTP scheme of the request. |
x |
|
Method |
String |
HTTP method of the request. |
x |
|
Request Uri |
String |
Full URI of the request. |
x |
|
Raw Request Uri |
String |
Full URI of the request, encoded as received. @since 1.5.0 |
x |
|
Query String |
String |
Query string of the request. |
x |
|
Local Address |
String |
Local host address from the server. |
x |
|
Remote Address |
String |
Remote host address from the sender. |
x |
|
Client Certificate |
Any |
Client certificate (if 2 way TLS is enabled). |
||
Query Params |
Object |
Query parameters map built from the parsed string. |
x |
|
Uri Params |
Object |
URI parameters extracted from the request path. |
x |
|
Request Path |
String |
Full path requested. |
x |
|
Headers |
Object |
Map of HTTP headers in the message. |
x |
Repeatable In Memory Stream
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Initial Buffer Size |
Number |
This is the amount of memory allocated in order to consume the stream and provide random access to it. If the stream contains more data than can be fit into this buffer, then the buffer expands according to the bufferSizeIncrement attribute, with an upper limit of maxInMemorySize. |
||
Buffer Size Increment |
Number |
How much the buffer size expands if it exceeds its initial size. Setting a value of zero or lower will mean that the buffer should not expand, meaning that a STREAM_MAXIMUM_SIZE_EXCEEDED error will be raised when the buffer gets full. |
||
Max Buffer Size |
Number |
This is the maximum amount of memory that the buffer can use. If the buffer uses more than that, a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised. A value lower or equal to zero means there’s no limit. |
||
Buffer Unit |
Enumeration, one of:
|
The unit in which all these attributes are expressed |
Repeatable File Store Stream
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max In Memory Size |
Number |
Defines the maximum memory that the stream can use to keep data in memory. If more than that is consumed, the content is buffered on disk. |
||
Buffer Unit |
Enumeration, one of:
|
The unit in which maxInMemorySize is expressed |
Redelivery Policy
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max Redelivery Count |
Number |
The maximum number of times a message can be redelivered and processed unsuccessfully before triggering process-failed-message |
||
Use Secure Hash |
Boolean |
Whether to use a secure hash algorithm to identify a redelivered message |
||
Message Digest Algorithm |
String |
The secure hashing algorithm to use. If not set, the default is SHA-256. |
||
Id Expression |
String |
Defines one or more expressions to use to determine when a message has been redelivered. This property may only be set if useSecureHash is false. |
||
Object Store |
ObjectStore |
The object store where the redelivery counter for each message is stored. |
TCP Client Socket Properties
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Connection Timeout |
Number |
Time to wait during a connection to a remote server before failing with a timeout. If the configured requester host resolves to multiple IP addresses, the host tries to connect to every single IP address. Therefore, if every connection times out, the number of resolved IP addresses multiplies the global connection timeout. |
30000 |
|
Send Tcp No Delay |
Boolean |
Indicates whether or not to collect the transmitted data for greater efficiency and send the data immediately. |
true |
|
Linger |
Number |
How long, in milliseconds, the socket takes to close, so any remaining data is transmitted correctly. |
||
Keep Alive |
Boolean |
Indicates whether the open socket connections unused for a long period and with an unavailable connection can be closed. |
false |
|
Fail On Unresolved Host |
Boolean |
Indicates whether the socket fails during its creation if the host set on the endpoint cannot be resolved. |
true |
|
Send Buffer Size |
Number |
Size of the buffer, in bytes, when sending data. |
||
Receive Buffer Size |
Number |
Size of the buffer, in bytes, when receiving data. |
||
Client Timeout |
Number |
Time, in milliseconds, that the socket waits in a blocking operation before failing. |
||
Reuse Address |
Boolean |
When trying to bind the port, indicates whether to reuse ( |
true |
Expiration Policy
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max Idle Time |
Number |
A scalar time value for the maximum amount of time a dynamic configuration instance should be allowed to be idle before it’s considered eligible for expiration |
||
Time Unit |
Enumeration, one of:
|
A time unit that qualifies the maxIdleTime attribute |
HTTP Response Attributes
To get familiar on how to use message attributes, refer to the about message attributes documentation.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Status Code |
Number |
HTTP status code of the response. |
x |
|
Reason Phrase |
String |
HTTP reason phrase of the response. |
x |
|
Headers |
Object |
Map of HTTP headers in the message. |
x |
Basic Authentication
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Username |
String |
The username to authenticate. |
x |
|
Password |
String |
The password to authenticate. |
x |
|
Preemptive |
Boolean |
Configures if authentication should be preemptive or not. Preemptive authentication will send the authentication header in the first request, instead of waiting for a 401 response code to send it. |
true |
Digest Authentication
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Username |
String |
The username to authenticate. |
x |
|
Password |
String |
The password to authenticate. |
x |
|
Preemptive |
Boolean |
Configures if authentication should be preemptive or not. Preemptive authentication will send the authentication header in the first request, instead of waiting for a 401 response code to send it. |
true |
NTLM Authentication
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Domain |
String |
The domain to authenticate. |
||
Workstation |
String |
The workstation to authenticate. |
||
Username |
String |
The username to authenticate. |
x |
|
Password |
String |
The password to authenticate. |
x |
|
Preemptive |
Boolean |
Configures if authentication should be preemptive or not. Preemptive authentication will send the authentication header in the first request, instead of waiting for a 401 response code to send it. |
true |
Proxy
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Host |
String |
Host where the proxy requests will be sent. |
x |
|
Port |
Number |
Port where the proxy requests will be sent. |
x |
|
Username |
String |
The username to authenticate against the proxy. |
||
Password |
String |
The password to authenticate against the proxy. |
||
Non Proxy Hosts |
String |
A list of comma separated hosts against which the proxy is not used |
NTLM Proxy
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Ntlm Domain |
String |
The domain to authenticate against the proxy. |
x |
|
Host |
String |
Host where the proxy requests will be sent. |
x |
|
Port |
Number |
Port where the proxy requests will be sent. |
x |
|
Username |
String |
The username to authenticate against the proxy. |
||
Password |
String |
The password to authenticate against the proxy. |
||
Non Proxy Hosts |
String |
A list of comma separated hosts against which the proxy is not used |
Success Status Code Validator
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Values |
String |
Status codes that will be considered. |
x |
Failure Status Code Validator
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Values |
String |
Status codes that will be considered. |
x |
Origin
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Url |
String |
URL of the Origins, from which the browser can load resources. |
x |
|
Access Control Max Age |
Number |
The amount of time, in seconds, to cache the results of a preflight request. |
x |
|
Allowed Methods |
Array of Method |
Indicates which HTTP methods are permitted while accessing the resources from the origin. |
||
Allowed Headers |
Array of Header |
In preflight requests, indicates the HTTP headers to use during the actual request. |
||
Expose Headers |
Array of Header |
Response headers exposed in the request. |