Contact Us 1-800-596-4880

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.

Configurations


Listener Configuration

Configuration element for a HttpListener.

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

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 true, requests with an invalid value for Transfer-Encoding header are rejected with a 400 Bad Request message. The valid values are chunked, deflate, compress, identity and gzip. These values are defined in RFC-7230 and RFC-2616.

false

Connection Types

Listener

Connection provider for a HttpListener, handles the creation of HttpServer instances.

Parameters
Name Type Description Default Value Required

TLS Configuration

TLS

Reference to a TLS config element. This will enable HTTPS for this config.

Protocol

Enumeration, one of:

  • HTTP

  • HTTPS

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:

  • ALWAYS

  • AUTO

  • NEVER

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:

  • AUTO

  • ALWAYS

  • NEVER

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:

  • AUTO

  • ALWAYS

  • NEVER

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

TLS

Reference to a TLS config element. This will enable HTTPS for this config.

Protocol

Enumeration, one of:

  • HTTP

  • HTTPS

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 tls:context child element of this listener-config. If not tls:context is defined, then the default JVM certificates are used to establish communication.

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

Associated Operations

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:

  • ALWAYS

  • AUTO

  • NEVER

Defines if the request should contain a body or not.

Request Streaming Mode

Enumeration, one of:

  • AUTO

  • ALWAYS

  • NEVER

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:

  • AUTO

  • ALWAYS

  • NEVER

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.

Output

Type

Any

Attributes Type

For Configurations.

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 Authorization header.

#[attributes]

Throws

  • HTTP:BASIC_AUTHENTICATION

  • MULE:SERVER_SECURITY

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.

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]

Output

Type

Any

Attributes Type

Any

Throws

  • HTTP:NOT_FOUND

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:

  • AUTO

  • ALWAYS

  • NEVER

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.

Output

Type

Any

Attributes Type

For Configurations.

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.

CRL File

Field Type Description Default Value Required

Path

String

The path to the CRL file.

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:

  • BYTE

  • KB

  • MB

  • GB

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:

  • BYTE

  • KB

  • MB

  • GB

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) or fail (false) the configured port.

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:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A time unit that qualifies the maxIdleTime attribute

Default Header

Field Type Description Default Value Required

Key

String

x

Value

String

x

Query Param

Field Type Description Default Value Required

Key

String

x

Value

String

x

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.

Method

Field Type Description Default Value Required

Method Name

String

HTTP method name.

x

Field Type Description Default Value Required

Header Name

String

HTTP header name.

x

View on GitHub