HTTP Request Connector

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

Studio Visual Editor:

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

Additionally, you must reference a global element, explained below.

Studio Visual Editor:

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.

XML Editor:

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.

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

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:

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

Below are two connectors sharing the same connector configuration:

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

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:

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.

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.

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. See documentation below.

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.

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

If query parameters should be set dynamically (for example, while at design time you don’t know how many query parameters are 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:

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 generates 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 resolve 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 is used.

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

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

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

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

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 generates 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 are 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 you to override parameters, if necessary. If the same parameter is defined more than once, the latest value is used.

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

This performs a GET request to http://www.example.com/test, adding the following headers:

This is exactly equivalent to setting outbound properties in the Mule message through properties transformers. Outbound properties map 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 need to be set:

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

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

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:

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

Just as with query parameters, the header and headers elements can be combined in the connector. They resolve 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 are used.

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 set the payload of your message to the form parameters to send:

For example, if you use the Set Payload element to set your payload:

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

A POST request is sent to http://www.example.com/test, with Content-Type: application/x-www-form-urlencoded, and the body is “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:

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

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

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

This example generates the same request as 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 resolve 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 you to override parameters, if necessary. If the same parameter is defined more than once, the latest values is used.

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

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:

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

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

This example generates 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 resolve 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 are used.

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

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

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

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

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

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

This example generates a GET request to http://www.example.com/test, adding the following header:

Just as with query parameters, the <http:header> and <http:headers> elements can be combined inside the request builder (<http:request-builder>). They resolve 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 you to override parameters if necessary. If the same parameter is defined more than once, the latest value is used.

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

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:

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

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:

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 raises an exception.

Studio Visual Editor:

XML Editor:

For example:

A range of failure status codes is defined by using two dots .., so in the example above, any value between 500 and 599 is considered a failure and raises an exception. If the HTTP response has any other status value, it’s considered a success.