Contact Us 1-800-596-4880
  1. Homepage
  2. HTTP Connector (0.3.6)

  3. HTTP Request Connector

All Connectors

HTTP Request Connector

The HTTP Request Connector provides the most practical way to consume an external HTTP service. When sending HTTP requests, you can choose what method to use (GET, POST, etc) and may include a body, headers, attachments, query parameters, form parameters and URI parameters. The response is then received by the connector and is passed on to the next element in your flow.

This connector can also implement HTTPS protocol and encrypt your communications via TLS, it can also implement authentication via basic authentication, OAuth or digest.

The request connector is especially handy when consuming a RESTful API that is described in a RAML file. If you reference the API’s RAML file in the connector’s configuration, it will proactively offer you the set of available resources and operations contained in the RAML file, as well as enforce the policies described in the file. It will also expose the API metadata to Studio, which can then be used by other elements such as the DataMapper to autocomplete fields and make configuration much easier.

The connector can also send HTTP requests to addresses that aren’t associated to any RAML file – you can simply assign an address, select an HTTP method and optionally add additional parameters to your request.

Basic Usage

In Studio, to instance this connector as an HTTP Request Connector (and not an HTTP Listener Connector), you must place it into the Process section of a flow (ie: anywhere except the beginning).

add+request+connector

Minimum Configuration

The following example shows the minimal configuration required for this connector:

Studio Visual Editor

Minimum Configuration for the Connector Instance

In the connector instance, provide a Path and a Method:

basic+request

Create a Global Element

Like with most connectors in Studio, a lot of the configuration is encapsulated in a separate reusable object that can then be referenced by as many instances of the connector as you like.

Having global configuration elements becomes especially useful when having multiple connectors that must use the same settings, in order to avoid repeating the same configuration in every request. In Studio you can also reference a RAML file in this element, which then provides metadata that makes the rest of the configuration easier.
basic+request2

Minimum Configuration for the Global Element

At the very least, you need to provide a host and a port

request+config+2

The above configuration will perform a GET request to http://www.example.com/test

XML Editor

For example:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081"/>

<flow name="example1">
    ...
    <http:request config-ref="HTTP_Request_Configuration" path="test" method="POST"/>
</flow>

Minimum Configuration for the Global Element

Like with most connectors in Studio, a lot of the configuration is encapsulated in a separate reusable object that sits outside the flow and can then be referenced by as many instances of the connector as you like. This element defines a server connection to a particular network interface and port and handles outbound requests to it and their responses. At the very least, you need to provide a host and a port in your global element:

Minimum Configuration for the Connector Instance

After you have defined the request-config, to actually send an HTTP request you need to configure a flow with an http:request element. In the connector instance, provide a Path and a Method, as well as a reference to a global element

The above configuration will perform a GET request to http://www.example.com/test

Studio Visual Editor

HTTP Connector Basic Configuration

You need to provide a path and method for your requests, as well as reference a Connector Configuration global element. Note that the path field doesn’t define the full path, but rather the subpath, within the host and after the optional base path that can be specified in the Connector Configuration global element.

You can also add as many parameters as you want, which can be headers, query parameters or uri parameters.

minimum

Property Description

Display Name

The name with which the element will be viewed in the flow.

Request Config

A reference to the Global Element. This field is required.

Path

The path where the request will be sent (without including the optional base path) configured in the global element.

Method

The type of HTTP request to send (GET, POST, DELETE, etc.). Optional, the default is GET.

Parameters

You can include additional parameters to the request, such as headers and query params by clicking the green plus sign at the top.

If the global element references a RAML file, the relevant parameters will be displayed according to the selected resource and method.
If you’ve referenced a RAML file in the global element, both the Path and Method fields will present you with a drop-down list of available options, based on what the RAML describes. Note that you’re also always free to write your own values in these fields.

Global Element Basic Configuration

raml+library-w+data
Property Description

Name

The name with which the configuration element will be referenced form instances of the connector.

Protocol

Choose between HTTP and HTTPS

Host

The host to which to send requests. This field is required.

Port

The port to which to send requests. This field is required.

Base Path

A base path within the host. Instances of the connector can then specify a subpath within this path.

RAML Location

Your connector can point to a RAML file, which makes it a lot easier to configure as Studio proactively offers intelligent suggestions based in the metadata defined in the RAML file. You can reference a RAML file on your local disk, one on an external URI, or you can pick one of the available ones in the Exchange by clicking Search RAML in Exchange.

Enable Datasense

The Enable DataSense checkbox allows Studio to use DataSense to expose metadata from the RAML file and interact with it on other elements in Studio.
If you complete the RAML Location field first, all of the other fields will be automatically populated based on what’s specified in the RAML.

The metadata from the RAML is obtained every time you open your project in Studio and then kept in cache until you close and reopen the project.

If the RAML file is modified, you can refresh the cache of it by clicking the button Reload RAML.

The metadata exposed by the connector to your flow may not be updated right away. In such a case, click the Refresh Metadata button in the metadata explorer.

XML Editor

HTTP Connector Basic Configuration

You need to provide a path and method for your requests, as well as reference a Connector Configuration global element. Note that the path field doesn’t define the full path, but rather the subpath, within the host and after the optional base path that can be specified in the Connector Configuration global element.

As child elements of this connector, you can add as many parameters as you want, which may be headers, query parameters or uri parameters.

<http:request config-ref="HTTP_Request_Configuration" path="test" method="POST" doc:name="HTTP"/>
Property Description

doc:name

The name with which the element will be viewed in the flow in Studio.

config-ref

A reference to a reusable Global Element that contains several configuration parameters. This property is required.

path

The path where the request will be sent (without including the base path) configured in the global element.

method

The type of HTTP request to send (GET, POST, DELETE, etc.). Optional, the default is GET.

By default, GET, HEAD and OPTIONS methods will not send the payload in the request (the body of the HTTP request will be empty). The rest of the methods will send the message payload as the body of your request.

Global Element Basic Configuration

Every HTTP Connector must reference a global configuration element that sits outside any flow in your project. This element encapsulates much of the common configuration parameters that can be reused by other connectors in your project and can be referenced by multiple instances of the connector. At the very least, you need to provide a host and a port:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP Request Configuration"/>
Property Description XML Sample

name

Name of the Global Element, used to reference inside connector instance.

 
name="HTTP_Request_Configuration"

protocol

Choose between HTTP and HTTPS

protocol="HTTPS"

host

Host to be used by all request elements that reference this config.

 
host="example.com"

port

Port to be used by all request elements that reference this config.

 
port="8081"

basePath

The path to which requests will be sent. You can then specify subfolders below this path within the connector instance.

 
basePath="/api/v2"

Child Element

Description

XML Sample

RAML Location

If you have access to a RAML file describing the API you’re connecting to, indicate its location here.

<http:raml-api-configuration location="t-shirt.raml"/>

The above configuration will perform a GET request to http://www.example.com/test

Below are two connectors sharing the same connector configuration:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="80" basePath="/api/v2" />

<flow name="test_flow">
    ...
    <http:request config-ref="HTTP_Request_Configuration" path="customer" method="GET" />
    ...
    <http:request config-ref="HTTP_Request_Configuration" path="item" method="POST" />
    ...
</flow>

The first connector in the example will send a GET request to http://www.example.com/api/v2/customer. The second connector will send a POST request to http://www.example.com/api/v2/item.

Mapping Between Mule Messages and HTTP Requests

When an HTTP Request Connector is executed, the MuleMessage that reaches it is transformed to generate an HTTP Request. Below is an explanation of how each part of the Mule Message contributes to generate an HTTP request.

HTTP Request Body

The Mule Message payload is converted into a byte array and sent as the HTTP Request’s body. This behavior is carried out always, except in the following scenarios:

  • The Mule Message’s Payload is a Map of keys and values

  • The Message has outbound attachments

Generate the Request Body with Content-Type:application/x-form-urlencoded

Whenever the message payload is a Map, the connector automatically generates an HTTP request with the header Content-Type:`application/x-www-form-urlencoded`. The keys and values of the map in the payload are converted into form parameter keys and values in the body of the HTTP request.

Generate the Request Body with Content-Type: multipart/form-data

Whenever the message contains outbound attachments, the connector automatically generates an HTTP Request with the header Content-Type:multipart/form-data. The payload of the Mule Message is ignored, and instead each attachment in the message is converted into a part of the HTTP Request body. If you want to create a different multipart request, then the Content-Type header can be set with a different value by adding Adding Custom Parameters.

HTTP Headers

If there are any outbound properties in the Mule message that arrives to the HTTP Request Connector, these are automatically added as HTTP request headers. It’s also possible to add headers explicitly through the HTTP Request Connector’s configuration.

By default, the Grizzly libraries used by the HTTP connector limit the HTTP request header section size (request line plus headers) to below 8192 bytes. While it is recommended that you keep your HTTP request header section below this limit, you can override this limit by setting mule.http.headerSectionSize to a larger value (in bytes). You can set this JVM parameter in the wrapper.conf file, or you can pass it in from the command line when you start the Mule runtime.

For example, to set the HTTP header section size to 16,000 bytes, you can start the Mule runtime with this command: + ./mule -M-Dmule.http.headerSectionSize=16000

Adding Custom Parameters

The HTTP Request connector allows you to include the following types of parameters:

  • query params

  • a map of multiple query params

  • uri params

  • a map of multiple uri params

  • headers

  • a map of multiple headers

Additionally, you can also send form parameters with your request, included in the Mule message payload. You can also include attachments in your request by adding an Attachment building block to your flow.

Studio Visual Editor

Remember that when using Studio, if the API you want to reach has a RAML file, referencing this RAML file in the global element will expose the API’s metadata, and Studio will proactively display all the available properties for each operation in the API.

Query parameters

By clicking the Add Parameter button you can add parameters to your request. If you leave the default query-param as the type of parameter, you can add new query parameters and assign names and values to them.

query+params

The above configuration will perform a GET request to http://www.example.com/test?k1=v1&k2=v2+.

Both the name and value fields allow using MEL expressions.

If query parameters should be set dynamically (for example, while in design time you don’t know how many query parameters will be needed in the request), then you can change the parameter type to query-params, which accepts an array, and you can assign it a MEL expression that returns a map of parameters:

query+params+2

For this example, you must first generate a variable named customMap. If you assign that variable a value through the following MEL expression:

#[{'k1':'v1', 'k2':'v2'}]

It will generate the same request than the previous example, a GET request to http://www.example.com/test?k1=v1&k2=v2+

The query-param and query-params elements can be combined inside a single connector. The parameters will be resolved for each request (evaluating all the MEL expressions in the context of the current message), and in the order they are specified inside the request builder. This allows to override parameters if necessary. If the same parameter is defined more than once, the latest value will be used.

URI parameters

When parameters should be part of the path, placeholders can be added in the path attribute with a name for each of them, and then they must be referenced by a uri-parameter:

uriparams

If you first type the placeholder into the path field, Studio will automatically add the corresponding uri-param below in the parameters section, saving you some of the hassle.

This will perform a GET request to http://www.example.com/customer/20.

Both the name and value allow using MEL expressions.

Dynamically setting URI parameters

If URI parameters should be set dynamically they can be set through a MEL expression that returns a map of parameters to set:

uriparams2
If any additional uri-param parameters are added automatically while you type the value in the path field, delete these, as they will be addressed by the dynamic uri-parmans field.

For this example you need to create a variable named customMap. If you set that variable to the MEL expression #[{'p1':'v1', 'p2':'v2'}], it will generate a GET request to +http://www.example.com/test/v1/v2+

Just as with query parameters, the uri-param and uri-params elements can be combined inside the connector. They will be resolved for each request (evaluating all the MEL expressions in the context of the current message), and in the order they are specified inside the request builder. This allows to override parameters if necessary. If the same parameter is defined more than once, the latest value will be used.

In every case, all the placeholders used in the path to reference URI parameters should match the names of the URI parameters inside the request builder (after all MEL expressions were evaluated).

Headers

You can add HTTP headers to the request just as easily as query parameters:

headers1

This will perform a GET request to http://www.example.com/test, adding the following headers:
HeaderName1: HeaderValue1
HeaderName2: HeaderValue2

Both the name and value allow using MEL expressions.

This is exactly equivalent to setting outbound properties in the Mule message through properties transformers. Outbound properties will be mapped as HTTP headers in the request. Thus, you could achieve the same by adding two properties transformers before the HTTP Request connector, one for each of the new headers that needs to be set:

w+properties+builders

In both cases, the headers of the response will be mapped as inbound properties of the Mule message after the response is processed.

Dynamically setting headers

If headers must be set dynamically (for example, you don’t know in design time how many extra headers will be needed in the request), they can be set through a MEL expression that returns a map of headers:

headers2

For the above example to work, you first need to generate a variable called customMap. If you set that variable to the following MEL expression:

#[{'TestHeader':'TestValue'}]

It will generate a GET request to http://www.example.com/test, adding the following header:

TestHeader: TestValue

Just as with query parameters, the header and headers elements can be combined in the connector. They will be resolved for each request (evaluating all the MEL expressions in the context of the current message), and in the order they are specified inside the request builder. This allows to override parameters if necessary. If the same parameter is defined more than once, the latest value will be used.

Sending form parameters in a POST request

In order to send parameters in a POST request, the payload of the Mule message should be a Map with the names and the values of the parameters to send. Hence, one way of sending form parameters in your request is adding a Set Payload element before the HTTP Request Connector to make the payload of your message equal to the form parameters you must send:

set+payload

  • For example, if you use the set payload element to set your payload the following:

#[{'key1':'value1', 'key2':'value2'}]

A POST request will be sent to http://www.example.com/test[ www.example.com/test], with Content-Type: application/x-www-form-urlencoded, and the body will be “key1=value1&key2=value2”; just as if a browser would have sent a request after the user submitted a form with these two values.

XML Editor

Query parameters

You can add query parameters by using the request-builder element inside the request:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <http:request request-config="HTTP_Request_Configuration" path="test" method="GET">
        <http:request-builder>
            <http:query-param paramName="k1" value="v1" />
            <http:query-param paramName="k2" value="v2" />
        </http:request-builder>
    </http:request>
</flow>

This will perform a GET request to http://www.example.com/test?k1=v1&k2=v2+.

Both the name and value allow using MEL expressions.

Dynamically Setting Query Parameters

If query parameters should be set dynamically (for example, you don’t know in design time how many query parameters will be needed in the request), they can be set through a MEL expression that returns a map of parameters:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <set-variable variableName="customMap" value="#[{'k1':'v1', 'k2':'v2'}]" />
    <http:request request-config="HTTP_Request_Configuration" path="test" method="GET">
        <http:request-builder>
            <http:query-params expression="#[flowVars.customMap]" />
        </http:request-builder>
    </http:request>
</flow>

This example will generate the same request than the previous one, a GET request to http://www.example.com/test?k1=v1&k2=v2+.

The query-param and query-params elements can be combined inside the request builder. The parameters will be resolved for each request (evaluating all the MEL expressions in the context of the current message), and in the order they are specified inside the request builder. This allows to override parameters if necessary. If the same parameter is defined more than once, the latest value will be used.

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <set-variable variableName="customMap" value="#[{'k2':'new', 'k3':'v3'}]" />

    <http:request request-config="HTTP_Request_Configuration" path="test" method="GET">
        <http:request-builder>
            <http:query-param paramName="k1" value="v1" />
            <http:query-param paramName="k2" value="v2" />
            <http:query-params expression="#[flowVars.customMap]" />
        </http:request-builder>
    </http:request>

</flow>

In this example, the parameter k2 defined in the map will override the k2 query-param defined earlier. The result will be a GET request to http://www.example.com/test?k1=v1&k2=new&k3=v3.

URI parameters

When parameters should be part of the path, placeholders can be added in the path attribute with a name for each of them, and then they must be referenced from the request builder to provide the values, using the uri-param element:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <http:request request-config="HTTP_Request_Configuration"  path="/customer/{customerId}" method="GET">
        <http:request-builder>
            <http:uri-param paramName="customerId" value="20" />
        </http:request-builder>
    </http:request>

</flow>

This will perform a GET request to http://www.example.com/customer/20.

Both the name and value allow using MEL expressions.

Dynamically setting URI parameters

If URI parameters should be set dynamically, they can be set through a MEL expression that returns a map of parameters to set:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <set-variable variableName="customMap" value="#[{'p1':'v1', 'p2':'v2'}]" />

    <http:request request-config="HTTP_Request_Configuration"  path="test/{p1}/{p2}" method="GET">
        <http:request-builder>
            <http:uri-params expression="#[flowVars.customMap]" />
        </http:request-builder>
    </http:request>
</flow>

This example will generate a GET request to +http://www.example.com/test/v1/v2+

Just as with query parameters, the uri-param and uri-params elements can be combined inside the request builder. They will be resolved for each request (evaluating all the MEL expressions in the context of the current message), and in the order they are specified inside the request builder. This allows to override parameters if necessary. If the same parameter is defined more than once, the latest value will be used.

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <set-variable variableName="customMap" value="#[{'p1':'new'}]" />

    <http:request request-config="HTTP_Request_Configuration"  path="test/{p1}/{p2}" method="GET">
        <http:request-builder>
            <http:query-param paramName="p1" value="v1" />
            <http:query-param paramName="p2" value="v2" />
            <http:query-params expression="#[flowVars.customMap]" />
        </http:request-builder>
    </http:request>
</flow>

In this example, the parameter p1 defined in the map will override the p1 uri-param defined earlier. The result will be a GET request to http://www.example.com/test?p1=new&p2=v2+.

In every case, all the placeholders used in the path to reference URI parameters should match the names of the URI parameters inside the request builder (after all MEL expressions were evaluated).

Headers

HTTP headers can be added to the request by using the "header" element inside the request-builder:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <http:request request-config="HTTP_Request_Configuration" path="test" method="GET">
        <http:request-builder>
            <http:header headerName="HeaderName1" value="HeaderValue1" />
            <http:header headerName="HeaderName2" value="HeaderValue2" />
        </http:request-builder>
    </http:request>
</flow>

This will perform a GET request to http://www.example.com/test, adding the following headers:
HeaderName1: HeaderValue1
HeaderName2: HeaderValue2

Both the name and value allow using MEL expressions.

Another way of sending headers is by setting outbound properties in the Mule message (current behavior of the HTTP transport). Outbound properties will be mapped as HTTP headers in the request. Thus, the following example is equivalent to the previous one:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <set-property propertyName="HeaderName1" value="HeaderValue1" />
    <set-property propertyName="HeaderName2" value="HeaderValue2" />

    <http:request request-config="HTTP_Request_Configuration" path="test" method="GET"/>
</flow>

In both cases, the headers of the response will be mapped as inbound properties of the Mule message after the response is processed.

Dynamically setting headers

If headers must be set dynamically (for example, you don’t know in design time how many extra headers will be needed in the request), they can be set through a MEL expression that returns a map of headers:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <set-variable variableName="customMap" value="#[{'TestHeader':'TestValue'}]" />

    <http:request request-config="HTTP_Request_Configuration" path="test" method="GET">
        <http:request-builder>
            <http:headers expression="#[flowVars.customMap]" />
        </http:request-builder>
    </http:request>
</flow>

This example will generate a GET request to http://www.example.com/test, adding the following header:
TestHeader: TestValue

Just as with query parameters, the header and headers elements can be combined inside the request builder. They will be resolved for each request (evaluating all the MEL expressions in the context of the current message), and in the order they are specified inside the request builder. This allows to override parameters if necessary. If the same parameter is defined more than once, the latest value will be used.

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <set-variable variableName="customMap"
      value="#[{'TestHeader2':'TestValueNew', 'TestHeader3':'TestValue3'}]" />

    <http:request request-config="HTTP_Request_Configuration" path="test" method="GET">
        <http:request-builder>
            <http:header paramName="TestHeader1" paramValue="TestValue1" />
            <http:header paramName="TestHeader2" paramValue="TestValue2" />
            <http:headers expression="#[flowVars.customMap]" />
        </http:request-builder>
    </http:request>
</flow>

In this example, the header TestHeader2 defined in the map will override the one defined earlier in the request builder. The result will be a GET request to http://www.example.com/test with the following headers:
TestHeader1: TestValue1
TestHeader2: TestValueNew
TestHeader3: TestValue3

Sending form parameters in a POST request

In order to send parameters in a POST request, the payload of the Mule message should be a Map with the names and the values of the parameters to send. Hence, one way of sending form parameters in your request is adding a Set Payload element before the HTTP Request Connector to make the payload of your message equal to the form parameters you must send:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <set-payload value="#[{'key1':'value1', 'key2':'value2'}]" />

    <http:request request-config="HTTP_Request_Configuration" path="test" method="POST"/>
</flow>

In this example, a POST request will be sent to http://www.example.com/test, with Content-Type: application/x-www-form-urlencoded, and the body will be "key1=value1&key2=value2"; just as if a browser would have sent a request after the user submitted a form with these two values.

Mapping Between HTTP Responses and Mule Messages

An HTTP response is mapped to the Mule Message in exactly the same way that the HTTP request is mapped to a Mule Message in the HTTP Listener Connector, except that the following elements don’t apply to HTTP responses:

  • Query parameters

  • URI parameters

  • All inbound properties related to the HTTP request URI

In addition, the HTTP Request Connector adds the following inbound properties to the Mule Message when receiving a response:

  • http.status: Status code of the HTTP response

  • http.reason: Reason phrase of the HTTP response

Disabling HTTP Response Body Parsing

As with the HTTP Listener Connector, when HTTP responses have a content type of application/x-www-form-urlencoded or multipart/form-data, the HTTP Request Connector automatically carries out a parsing of the message. If you wish, you can disable this parsing functionality by doing the following:

  • XML Editor: set the parseResponse attribute to false

  • Studio UI: Uncheck the Parse Response checkbox in the Advanced tab of the HTTP Request Connector

HTTP Response Validation

When the HTTP Request Connector receives an HTTP response, it validates the response through its status code. By default, it throws an error when the status code is higher or equal to 400. This means that if the server returns a 404 (Resource Not Found) or a 500 (Internal Server Error) the HTTP Request Connector will fail and the exception strategy of the flow it’s in will be executed.

You can change the set of valid HTTP response codes by setting one of the following two behaviors:

  • Success Status Code Validator: All the status codes defined within this element are considered valid, the request will throw an exception for any other status code.

  • Failure Status Code Validator: All the status codes defined within this element are considered invalid and an exception will be thrown, the request will be consider valid with any other status code.

To set a list of status codes accepted as success responses, do the following:

Studio Visual Editor

  1. Select the advanced tab of the HTTP Request Connector

  2. Select the Success Status Code Validator radio button

  3. Fill in the Values field below with 200,201

XML Editor

For example:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">

    ...

    <http:request request-config="HTTP_Request_Configuration"  path="/" method="GET">
         <http:success-status-code-validator values="200,201"/>
    </http:request>
</flow>

See full XML Code

<mule xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
    xmlns:spring="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd">

     <http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
    <http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

    <flow name="test_flow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <http:request request-config="HTTP_Request_Configuration"  path="/" method="GET">
            <http:success-status-code-validator values="200,201"/>
        </http:request>
</flow>

</mule>

In the example above, the list of accepted status codes is defined separated by commas, so only 200 and 201 are considered valid responses. If the HTTP response has any other status value, it’s considered a failure and will raise an exception.

Studio Visual Editor

  1. Select the advanced tab of the HTTP Request Connector

  2. Select the Failure Status Code Validator radio button

  3. Fill in the Values field below with `500..599 `

XML Editor

For example:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">

    ...

    <http:request request-config="HTTP_Request_Configuration"  path="/" method="GET">
         <http:failure-status-code-validator values="500..599"/>
    </http:request>
</flow>

See full XML Code

<mule xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
    xmlns:spring="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd">

     <http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
    <http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

    <flow name="test_flow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <http:request request-config="HTTP_Request_Configuration"  path="/" method="GET">
            <http:failure-status-code-validator values="500..599"/>
        </http:request>
    </flow>

</mule>

In the example above, a range of failure status codes is defined by using a -, so any value between 500 and 599 is considered a failure and will raise an exception. If the HTTP response has any other status value, it’s considered a success.

Changing the Default Behavior for When to Add a Body to the Request

By default, the methods GET, HEAD and OPTIONS will send HTTP requests with an empty body, and the payload of the Mule message won’t be used at all. The rest of the methods will send the message payload as the body of the request. If you need to change this default behavior, you can specify the sendBodyMode attribute in the request, with one of the following possible values:

  • AUTO (default): The behavior will depend on the method. Body will not be sent for GET, OPTIONS and HEAD, and it will be sent otherwise.

  • ALWAYS: The body will always be sent.

  • NEVER: The body will never be sent.

Studio Visual Editor

For example, GET requests usually do not contain a body, but some APIs require them to have one. In those cases, enter the Advanced settings panel and set the Send Body field to ALWAYS.

XML Editor

For example, GET requests usually do not contain a body, but some APIs require them to have one. In those cases, the sendBodyMode attribute should be specified to force this behavior:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    ...
    <set-payload value="Hello world" />
    <http:request request-config="HTTP_Request_Configuration" path="test" method="GET" sendBodyMode="ALWAYS"  />
</flow>

This will send a GET request to http://www.example.com/test with "Hello world" as the body.

Configuring Source and Target

By default, the body of your request is taken from the [payload] of the incoming Mule message and the response is sent onwards as the [payload] of the output Mule message, you can change this default behavior through the source and target attributes.

Studio Visual Editor

Attribute Description

source

Where to take the body of the request from. By default, this is #[payload]

target

Where to place response body. Default: #[payload]

Use this attribute to specify an alternate place other than payload for the output data, such as a variable or property.

For example:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test">
    ...
    <http:request config-ref="HTTP_Request_Configuration" path="test" method="GET"  source="#[message.inboundProperties.foo]" target="#[message.outboundAttachments.bar]" />
</flow>

This will take the body of the request from an inbound property named "foo", and place the response of the request in an outbound attachment named "bar".

XML Editor

Attribute Description

source

Where to take the body of the request from. Default: #[payload]

target

Where to place response body. Default: #[payload]

Use this attribute to specify an alternate place other than payload for the output data, such as a variable or property.

For example:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test">
    ...
    <http:request config-ref="HTTP_Request_Configuration" path="test" method="GET"  source="#[message.inboundProperties.foo]" target="#[message.outboundAttachments.bar]" />
</flow>

This will take the body of the request from an inbound property named "foo", and place the response of the request in an outbound attachment named "bar".

Configuring Streaming

By default, if the type of the payload is a stream, streaming will be used to send the request. You can change this default behavior by setting the attribute requestStreamingMode, which allows the following values:

  • AUTO (default): The behavior will depend on the payload type: if the payload is an InputStream, then streaming will be enabled; otherwise it will be disabled.

  • ALWAYS: Always do streaming regardless of the payload type.

  • NEVER: Never do streaming, even if the payload is a stream.

When streaming, the request does not contain the Content-Length header. Instead, it contains the Transfer-Encoding header: it sends the body in chunks until the stream is fully consumed.

Studio Visual Editor

For example, if your input is a file inbound endpoint that set a stream as the payload of the Mule message but you want to disable streaming, enter the Advanced settings panel and set the Enable Streaming field to NEVER.

XML Editor

The following example will make a POST request to http://www.example.com/test, reading a file from the "input" directory, and sending its content as the body of the request. In this case, streaming will be used because the file inbound endpoint will set a stream as the payload of the Mule message that is generated. The generated HTTP request will be sent using Transfer-Encoding: chunked.

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test">
    <file:inbound-endpoint path="input" responseTimeout="10000" />
    <http:request request-config="HTTP_Request_Configuration"   path="test" method="POST" />
</flow>

For streaming to be disabled in this case, we need to explicitly set ` requestStreamingMode`="NEVER"

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test">
    <file:inbound-endpoint path="input" responseTimeout="10000" />
     <http:request request-config="HTTP_Request_Configuration"   path="test" method="POST" requestStreamingMode="NEVER"/>
</flow>

In this case, the request will not be streamed.

Sending Multipart Requests

To send a multipart request (for example to upload a file in a POST request), outbound attachments should be set in the Mule message. When the message has attachments, a multipart request will be sent where each part is an attachment. In this case the payload is ignored.

Studio Visual Editor

You can use Attachment transformers to add attachments to your message:

This will send a POST request with ContentType: multipart/form-data and with two parts: one with the first attachment, the other with the second one.

XML Editor

For example:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    <set-attachment attachmentName="key1" value="value1" contentType="text/plain" />
    <set-attachment attachmentName="key2" value="value2" contentType="text/plain" />
    <http:request path="test" method="POST"  request-config="HTTP_Request_Configuration" />
</flow>

This will send a POST request to http://www.example.com/test, with ContentType: multipart/form-data and with two parts: one with name key1 and content value1, and the other one with name key2 and content value2.

If the response is a multipart response, then the parts will be mapped as inbound attachments in the Mule message, and the payload will be null.

HTTPS Protocol Configuration

You can send your requests through HTTPS protocol by simply setting the protocol attribute to HTTPS. This will make the HTTP Request Connector use the default JVM values for the HTTPS connection, which will likely already include a trust store with certificates for all the major certifying authorities.

See TLS Configuration for more details.

Studio Visual Editor

In the connector’s Global Configuration Element, on the General tab, select the HTTPS radio button to select the Protocol.

XML Editor

For example:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" protocol="HTTPS" doc:name="HTTP_Request_Configuration"/>

<flow name="test_flow">
    ...
    <http:request path="test" method="POST"  request-config="HTTP_Request_Configuration" />
</flow>

This will send a POST request to http://www.example.com/test, encrypted with the default JVM certificates.

If you want to use a different set of HTTPS certificates, you can customize them by setting the TLS configuration in the HTTP Request Connector’s global configuration element. You can also create a separate TLS global element and reference it through your HTTP Connector.

Studio Visual Editor

  1. In the connector’s Global Configuration Element, in the General tab, select the HTTPS radio button to select the Protocol.

  2. Select the TLS/SSL tab

  3. Either:

    • * Select the *Use TLS Config option and provide your credentials in the available fields.

      • Or select the Use Global TLS Config option, then select an existing configuration or create a new one by clicking the green plus sign next to the selection box.

XML Editor

You can add your TLS credentials as a child element of the http:request-config element:

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" protocol="HTTPS" doc:name="HTTP_Request_Configuration"/>
        <tls:context>
            <tls:trust-store path="your_truststore_path" password="your_truststore_password"/>
            <tls:key-store path="your_keystore_path" password="your_keystore_path" keyPassword="your_keystore_keypass"/>
        </tls:context>
</http:request-config>

<flow name="test_flow">
    ...
    <http:request path="test" method="POST"  request-config="HTTP_Request_Configuration" />
</flow>

The above example will send a POST request to http://www.example.com/test, encrypted with the provided HTTPS settings.

You can also add your TLS credentials in a separate construct, outside your http:request-config element. In that case, you must name your tls:context and add a tlsContext-ref attribute in your http:request-config.

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" tlsContext-ref="My-TLS_Context" protocol="HTTPS" doc:name="HTTP_Request_Configuration"/>

<tls:context name="My-TLS_Context" doc:name="My-TLS_Context">
        <tls:trust-store path="your_truststore_path" password="your_truststore_password"/>
        <tls:key-store path="your_keystore_path" password="your_keystore_path" keyPassword="your_keystore_keypass"/>
</tls:context>

<flow name="test_flow">
    ...
    <http:request path="test" method="POST"  request-config="HTTP_Request_Configuration" />
</flow>

Other Attributes

Other attributes in this connector allow you to set up more advanced functionality: response timeout, if redirects will be followed and if responses will be parsed.

Studio Visual Editor

These attributes are available in the *Advanced*tab in the connectors properties editor.

Attribute Description

Response Timeout

Specifies the time in milliseconds after which, if no response is received, the request will no longer be attempted.

Parse Response

If true, it will parse the response if you receive multipart responses. If set to false, no parsing will be done and the raw contents of the response are placed in the payload. By default it’s set to true.

Follow Redirects

Defines whether redirects are followed or not. This is set to true by default.

XML Editor

These attributes are available in the Advancedtab in the connectors properties editor.

Attribute Description

responseTimeout

Specifies the time in milliseconds after which, if no response is received, the request will no longer be attempted.

parseResponse

If true, it will parse the response if you receive multipart responses. If set to false, no parsing will be done and the raw contents of the response are placed in the payload. By default it’s set to true.

followRedirects

Defines whether redirects are followed or not. This is set to true by default.

See Also