Nav

HTTP Request Configuration Reference

A typical use of the HTTP Request operation is to consume an external HTTP service using the default GET method. By default, GET and OPTIONS methods do not send the payload in the request; the body of the HTTP request is empty. The other methods send the message payload as the body of your request.

After sending the request, the connector receives the response and passes it to the next element in the flow.

The required minimum setting for the request operation is a host URI, which can include a path. You can configure the following types of authentication in the request operation:

  • Basic

  • OAuth

  • NT LAN Manager (NTLM)

  • Digest

Mapping Between Mule Messages and HTTP Requests

By default, the HTTP request operation sends the Mule message payload as the HTTP request body but you can customize it using a DataWeave script or expression.

Adding Custom Parameters

In addition to the body of the request, you can configure:

  • Headers

  • Query parameters

  • URI parameters

  • A map of multiple headers or parameters

By default, the HTTP connector limits the HTTP request header section size (request line + headers) to 8191 bytes maximum. To increase the number of bytes in the allowed header section, set mule.http.headerSectionSize in the wrapper.conf file or on the command line when you start Mule runtime as follows:

./mule -M-Dmule.http.headerSectionSize=16000

Headers

Select Headers to add headers to the request. For example, add header names HeaderName1 and HeaderName2, add header values HeaderValue1 and HeaderValue2. You can use DataWeave expressions, for example #[{'HeaderName1' : 'HeaderValue1', 'HeaderName2' : 'HeaderValue2'}].

Query Parameters

In General > Request > Query Parameters, click + to add a parameter to a request. Type a name and value for the parameter or use a DataWeave expression to define the name and value.

URI Parameters

You configure a URI parameter when you want to use a placeholder, such as /customer/{customerId}, in the path of your request. To configure a URI parameter, in General, type the placeholder enclosed in curly brackets in Path. Select URI Parameters, click +, and enter a name and value. For example, enter customerId and 20 as the name and value.

customerId 20

Alternatively, you can use DataWeave expressions in the name and value fields.

When the app runs, it will perform a GET request to http://www.example.com/customer/20.

Dynamic Parameters and Headers.

If at design time, you don’t know how many query parameters or headers a request might need, use DataWeave and a variable map to dynamically assign parameters or headers to the request.

For example, you create a Map variable named customMap and assign the variable a map of values using DataWeave, then use that variable to set up the headers of your request:

#[customMap ++ {'HeaderName1' : 'HeaderValue1'}]

To set URI parameters dynamically, use a DataWeave expression that returns a map of the parameters. For example:

  • Set Path to /test/{p1}/{p2}

  • URI Parameter names: p1 and p2

  • URI Parameter value: #[customMap]

  • Before the request, assuming p1 already set: #[customMap ++ {'p2': 'customer'}]

The connector resolves parameters for each request, evaluating DataWeave expressions in the context of the current message, in the order specified in the request. If the same parameter is defined more than once, the latest value is used.

Sending Form Parameters in a POST Request

To send parameters in a POST request, In General > Request, select the POST method. In Body, construct the payload of the Mule message as application/x-www-form-urlencoded with the names and the values of the parameters to send. For example:

#[output application/x-www-form-urlencoded --- {'key1':'value1', 'key2':'value2'}]

A POST request is sent to the host location you specify with Content-Type: application/x-www-form-urlencoded, and the body is “key1=value1&key2=value2”.

Mapping Between HTTP Responses and Mule Messages

An HTTP response is mapped to the Mule message similar to the way the HTTP request is mapped to a Mule message. The following elements don’t apply to HTTP responses:

  • Query parameters

  • URI parameters

  • Inbound attributes related to the HTTP request URI

In addition, the HTTP request operation adds the following attributes to the Mule message when receiving a response:

  • attributes.statusCode: Status code of the HTTP response

  • attributes.reasonPhrase: Reason phrase of the HTTP response

Round-Robin Requests

The request operation connects to configured hosts using round robin DNS. Mule Runtime resolves all IP addresses associated to the specified host and performs load balancing by distributing the requests across all returned IPs.

When connecting to resources that require authentication, the external service needs to replicate session information between IP addresses under the host of your service. Otherwise, your requests might get rejected for being unauthorized.

When your external resource does not handle sticky sessions you need to add the service host name to the mule.http.disableRoundRobin system property when starting the Mule Runtime:


         
      
1
./mule -M-Dmule.http.disableRoundRobin=serverhostname.com

When configured in this way, the request does not use round robin DNS when connecting to that configured host.

HTTP Response Validation

When the HTTP request operation receives an HTTP response, it validates the response through its status code. By default, it throws an error when the status code is higher than or equal to 400. Consequently, if the server returns a 404 (Resource Not Found) or a 500 (Internal Server Error) a failure occurs and error handling is triggered.

You can change the set of valid HTTP response codes by configuring General > Response > Response Validator.

  • None: No validation occurs.

  • Expression: Validation occurs per the DataWeave expression you construct.

  • Success Status Code Validator: All the status codes defined within this element are considered valid; the request throws an error for any other status code.

  • Failure Status Code Validator: All the status codes defined within this element are considered invalid and an error is thrown; the request is considered valid with any other status code.

To set which status codes are acceptable as successful responses, in General > Response > Response Validator, select Success Status Code Validator. In Values, enter the list of acceptable status codes, separated by commas. For example: 200,201. If the HTTP response has any other status value, it fails and raises an error.

A range of failure status codes is defined by two ASCII full stop characters ... Any value between 500 and 599 is considered a failure and raises an error. If the HTTP response has any other status value, it’s considered a success.

Configuring a Target

By default, the body of a 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 General > Request > Body and General > Output > Target Variable attributes. Use this attribute to specify a location other than payload for the output data, such as a variable.

Configuring Request Streaming

By default, if the type of the payload is a stream, streaming is used to send the request. You can change this default behavior. Select General > Request > Request Streaming with one of the following values:

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

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

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

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

Configuring Client Streaming

In Mule Enterprise Edition, HTTP client streaming is enabled by default. You can set the following attributes to manage streaming:

  • responseBufferSize

  • mule.http.disableResponseStreaming, a system property

HTTP requests are all nonblocking.