HTTP Response Builder

In Mule 3.6 and later, the legacy endpoint-based HTTP connector has been replaced with an operation-based HTTP connector. The HTTP Response Builder is also deprecated.

In Anypoint Studio version 6, HTTP Response Builder is only supported for development with XML and not with the Visual Studio Editor.

When the HTTP Connector works as a listener, you can configure a status code and a status reason on the connector itself, separately for both success and failure scenarios. To generate a response from an HTTP template, use the Parse Template element.

See HTTP Connector for information about the 3.6 and later operation-based HTTP connector. For information on the deprecated HTTP connector, see HTTP Connector - Deprecated.

The HTTP response builder is an HTTP component that allows you to easily configure HTTP responses. It replaces the content of the message payload with the HTTP response, allowing you to provide custom responses to an application. Typically, the response builder is used at the last step before returning a response to the user, although it is still possible to perform more steps to alter the payload after it.

A scenario where the response builder is particularly useful is when building a RESTful API, where you may wish to generate different responses or custom error messages to reply to specific resource requests.

Example 1
Example 2

Basic Anatomy

The implementation of the HTTP Response Builder transforms the payload to the class org.mule.transport.http.HTTPResponse.

An HTTP response has two elements, which are built at runtime:

A body
Headers

Body

The existing Mule Message Payload becomes the body of the HTTP response.

Headers

The most common HTTP headers are set up as attributes of the <http:response-builder> element.

Attribute Description

Attribute	Description
status	HTTP status code of the response. Default: 200.
contentType	If no content type is specified, then the content type of the message is used. If the message has no content type, then the default content type is `text/plain`. Example: `text/html; charset=utf-8`.

status

HTTP status code of the response. Default: 200.

contentType

If no content type is specified, then the content type of the message is used. If the message has no content type, then the default content type is text/plain. Example: text/html; charset=utf-8.

<http:response-builder doc:name="HTTP Response Builder" contentType="text/xhtml" status="201"/>

Other common HTTP response headers are defined in their own child element within <http:response-builder>:

Child Element	Description
cache-control	Tells all caching mechanisms from server to client whether they may cache this object. Allows to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain.
expires	Provides a date/time after which the response is considered stale. Specifies when the cookie expires. Accepted formats are Wdy, DD Mon YYYY HH:MM:SS GMT.
location	Used in redirection or when a resource has been created.

Child Element

Description

cache-control

Tells all caching mechanisms from server to client whether they may cache this object. Allows to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain.

expires

Provides a date/time after which the response is considered stale. Specifies when the cookie expires. Accepted formats are Wdy, DD Mon YYYY HH:MM:SS GMT.

location

Used in redirection or when a resource has been created.

<http:location value="http://localhost:8080/resources/client/5"/>

The cache-control element has the following configurable attributes:

Attribute	Description
directive	Can be set to public or private.
maxAge	When the max-age cache-control directive is present in a cached response, the response is stale if its current age is greater than the age value given. If a response includes both an Expires header and a max-age directive, the max-age directive overrides the Expires header, even if the Expires header is more restrictive.
mustRevalidate	When true, that cache MUST NOT use the entry after it becomes stale to respond to a subsequent request without first revalidating it with the origin server.
noCache	If set to true, a cache MUST NOT use the response to satisfy a subsequent request without successful revalidation with the origin server.
noStore	If set to true, prevents the inadvertent release or retention of sensitive information.

Attribute

Description

directive

Can be set to public or private.

maxAge

When the max-age cache-control directive is present in a cached response, the response is stale if its current age is greater than the age value given. If a response includes both an Expires header and a max-age directive, the max-age directive overrides the Expires header, even if the Expires header is more restrictive.

mustRevalidate

When true, that cache MUST NOT use the entry after it becomes stale to respond to a subsequent request without first revalidating it with the origin server.

noCache

If set to true, a cache MUST NOT use the response to satisfy a subsequent request without successful revalidation with the origin server.

noStore

If set to true, prevents the inadvertent release or retention of sensitive information.

Any other headers are configurable by adding an additional child element of the type http:header.

<http:header name="link" value="&lt;/feed&gt;"/>

The Cache-Control header can be extended if necessary by adding an http:header for the Cache-Control.

You can also include cookies into the headers by adding the child element <http:set-cookie>. This element has the following configurable attributes:

Attribute	Description
name	(Required.) The name of the cookie.
value	(Required.) The value of the cookie.
domain	The domain scope of the cookie.
path	The path scope of the cookie.
expiryDate	The exact date/time when the cookie expires. It must be specified in the form Wdy, DD Mon YYYY HH:MM:SS GMT. This attribute is not allowed if maxAge is defined.
maxAge	Indicates, in seconds, the max age of the cookie. This attribute is not allowed if expiryDate is defined.
secure	A boolean to specify that the cookie communication should be limited to encrypted transmission. Default is false.
version	Sets the version of the cookie specification to which this cookie conforms.

Attribute

Description

name

(Required.) The name of the cookie.

value

(Required.) The value of the cookie.

domain

The domain scope of the cookie.

path

The path scope of the cookie.

expiryDate

The exact date/time when the cookie expires. It must be specified in the form Wdy, DD Mon YYYY HH:MM:SS GMT. This attribute is not allowed if maxAge is defined.

maxAge

Indicates, in seconds, the max age of the cookie. This attribute is not allowed if expiryDate is defined.

secure

A boolean to specify that the cookie communication should be limited to encrypted transmission. Default is false.

version

Sets the version of the cookie specification to which this cookie conforms.

<http:set-cookie name="userId" value="5" path="/" version="1.0" maxAge="10000"/>

All of the configurable values inside the HTTP response element support expressions.

Any outbound properties that were already present in the message are also propagated outwards together with the response headers. To avoid this, it is recommended that unwanted outbound properties are removed in a previous step by using a remove-property transformer.

Note that Headers set by the HTTP response builder overwrite outbound properties of the same name.

Example 1

A common use case occurs in flows that are consumed by third-party monitoring tools which require either an empty response with a 200 status code, or some custom response. In this first example, the HTTP Response Builder simply returns a 200 status code.

In a new flow, add an http:inbound-endpoint element.
```
<http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" path="ex1" doc:name="HTTP"/>
```
Attribute Value

exchange-pattern

request-response

host

localhost

port

8081

path

ex1

doc:name

HTTP

The service is now reachable through the URL http://localhost:8081/ex1.
Below the HTTP inbound element, add an http:response-builder element.
```
<http:response-builder status="200" contentType="text/html" doc:name="HTTP Response Builder"/>
```
Attribute Value

status

200

contentType

text/html

doc:name

HTTP Response Builder
Save, then run your project.
Send the HTTP endpoint a POST HTTP request to` http://localhost:8081/ex1`.

The easiest way to do this is to send a POST via a browser extension such as Postman (for Google Chrome) or the curl command line utility.
```
curl -X POST http://localhost:8081/ex1
```
This returns a few headers, a cookie and a status code of 200.

Attribute	Value
exchange-pattern	request-response
host	localhost
port	8081
path	ex1
doc:name	HTTP

Attribute	Value
status	200
contentType	text/html
doc:name	HTTP Response Builder

Example 1 Full Code

<?xml version="1.0" encoding="UTF-8"?>

<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">
<flow name="just-response-code" doc:name="just-response-code">
    <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" path="ex1" doc:name="HTTP"/>
    <http:response-builder status="200" contentType="text/html" doc:name="HTTP Response Builder"/>
</flow>
</mule>

Example 2

In this second example, the payload is populated with some HTML before reaching the HTTP Response Builder. The HTTP Response Builder changes the message object type and adds a series of headers, but doesn’t alter the HTML content that is passed on to it.

In a new flow add an http:inbound-endpoint element
```
<http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" path="ex2" doc:name="HTTP"/>
```
Attribute Value

exchange-pattern

request-response

host

localhost

port

8081

path

ex2

doc:name

HTTP

The service is now reachable through the URL http://localhost:8081/ex2.
Below the HTTP inbound element, add a set-payload element:
```
<set-payload doc:name="Set Payload" value="&lt;HTML&gt;&lt;BODY&gt;hello world&lt;/BODY&gt;&lt;/HTML&gt;"/>
```
Attribute Value

value

<HTML><BODY>hello world</BODY></HTML>

This value becomes the payload of the Mule message.
Below the set payload element, add an http:response-builder element
```
<http:response-builder status="200" contentType="text/html" doc:name="HTTP Response Builder"/>
```
Attribute Value

status

200

contentType

text/html

doc:name

HTTP Response Builder
Save, then run your project.
Send the HTTP endpoint a POST HTTP request to` http://localhost:8081/ex2`.

The easiest way to do this is to send a POST via a browser extension such as Postman (for Google Chrome) or the curl command line utility.
```
curl -X POST http://localhost:8081/ex2
```
This returns a few headers, a cookie and a status code of 200 and the following payload:
```
<HTML>
    <BODY>hello world</BODY>
</HTML>
```

Attribute	Value
exchange-pattern	request-response
host	localhost
port	8081
path	ex2
doc:name	HTTP

Attribute	Value
value	<HTML><BODY>hello world</BODY></HTML>

Attribute	Value
status	200
contentType	text/html
doc:name	HTTP Response Builder

Example 2 Full Code

<?xml version="1.0" encoding="UTF-8"?>

<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">
<flow name="receives-string" doc:name="receives-string">
    <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8082" path="ex2" doc:name="HTTP"/>
    <set-payload doc:name="Set Payload" value="&lt;HTML&gt;&lt;BODY&gt;iamalive&lt;/BODY&gt;&lt;/HTML&gt;"/>
    <http:response-builder doc:name="HTTP Response Builder"/>
</flow>
</mule>

HTTP Response Builder

Basic Anatomy

Body

Headers

Example 1

Example 1 Full Code

Example 2

Example 2 Full Code

See Also