HTTP Transport Reference

Introduction

The HTTP transport provides support for exposing applications over HTTP and making HTTP client requests from Mule flows to external services. Mule supports inbound, outbound, and polling HTTP endpoints. These endpoints support all common features of the HTTP spec, such as ETag processing, cookies, and keepalive. Both HTTP 1.0 and 1.1 are supported.

HTTP/S endpoints are synchronous by default, so you do not have to set exchange-pattern="request-response". If you set exchange-pattern="one-way", the messages are sent asynchronously. Note that if you're doing an asynchronous POST, streaming is disabled.

Transport Info

Transport	Doc	Inbound	Outbound	Request	Transactions	Streaming	Retries	MEPs	Default MEP	Maven Artifact
HTTP	JavaDoc SchemaDoc							one-way, request-response	request-response	org.mule.transport:mule-transport-http
HTTPS	JavaDoc SchemaDoc							one-way, request-response	request-response	org.mule.transport:mule-transport-https

Namespace and Syntax

XML schema location

Syntax

URI example

http://theUser:secret@theHost:port/path?query

XML version

Features

• Server as an HTTP server or client
• Create HTTP services such as SOAP, REST or XML-RPC
• Make HTTP requests to external services
• Support for polling an HTTP endpoints including ETag support
• Transfer binary or text files, including forms and attachment
• Security including SSL, certificates and Authentication
• Build flows to different paths on the same port
• Support for reading and writing cookies
• Streaming for transferring large files
• Custom HTTP header support
• Redirect Handling
• Handling of Content-Type and Encoding
• Serve up static content such as HTML, JavaScript, Images and CSS (since Mule 3.2)

Basic Usage

To create a HTTP server you just need to create a flow with an inbound HTTP endpoint:

This with accept incoming HTTP requests on http://localhost:8080/moon and echo the response back to the client.

To make a client invocation of an HTTP endpoint you need to configure an outbound endpoint on your flow or you can use the MuleClient to invoke an HTTP endpoint directly in your code.

Or from within your code:

Finally, you can reference an endpoint by name from your Mule configuration in the Mule client. From the previous example we can create a global HTTP endpoint that cna be referenced from the flow or from code:

Global endpoints allow you to remove actual addresses from you code and flows so that you can move Mule applications between environments.

Security

You can use the HTTPS Transport Reference to create secure connections over HTTP. If you want to secure requests to your HTTP endpoint, the HTTP connector supports HTTP Basic/Digest authentication methods (as well as the Mule generic header authentication). To configure HTTP Basic, you configure a Security Endpoint Filter on an HTTP endpoint.

You must configure the security manager on the Mule instance against which this security filter will authenticate. For information about security configuration options and examples, see Configuring Security. For general information about endpoint configuration, see Configuring Endpoints.

HTTP Response Header

The default behaviour of the HTTP connector is to return, among other things, the X_MULE_SESSION header as part of every HTTP response. The content of this header is a base64-encoded Java serialized object. As such, if you decode the value and look at the plain text, you can view all the names and values of the properties stored in the Mule session.  To tighten security, you can remove that property from service responses with the following code.

Sending Credentials

If you want to make an HTTP request that requires authentication, you can set the credentials on the endpoint:

http://user:password@mycompany.com/secure

Cookies

If you want to send cookies along on your outgoing request, simply configure them on the endpoint:

Polling HTTP Services

The HTTP transport supports polling an HTTP URL, which is useful for grabbing periodic data from a page that changes or to invoke a REST service, such as polling an Amazon Queue.

To configure the HTTP Polling receiver, you include an HTTP polling-connector configuration in your Mule configuration:

To use the connector in your endpoints, use:

Handling HTTP Content-Type and Encoding

Sending

The following behavior applies when sending POST request bodies as a client and when returning a response body:

For a String, char[], Reader, or similar:

• If the endpoint has encoding set explicitly, use that
• Otherwise, take it from the message's property Content-Type
• If none of these is set, use the Mule Context's configuration default.
• For Content-Type, send the message's property Content-Type but with the actual encoding set.

For binary content, encoding is not relevant. Content-Type is set as follows:

• If the Content-Type property is set on the message, send that.
• Send "application/octet-stream" as Content-Type if none is set on the message.

Receiving

When receiving HTTP responses, the payload of the MuleMessage will always be the InputStream of the HTTP response.

Including Custom Header Properties

When making a new HTTP client request, Mule filters out any existing HTTP request headers because they are often from a previous request. For example, if you have an HTTP endpoint that proxies another HTTP endpoint, you wouldn't want to copy the Content-Type header property from the first HTTP request to the second request.

If you do want to include HTTP headers, you can specify them as properties on the outbound endpoint as follows:

or use Message Properties Transformer, as follows:

Building the Target URL from the Request

The HTTP request URL is available in the Mule header. You can access this using the header expression evaluator #[header:http.request]. For example, if you want to redirect the request to a different server based on a filter, you can build the target URL as shown below:

Handling Redirects

To redirect an HTTP client, you must set two properties on the endpoint. First, set the http.status property to '307', which instructs the client that the resource has be temporarily redirected. Alternatively, you can set the property to '301' for a permanent redirect. Second, set the Location property, which specifies the location where you want to redirect your client.

See the HTTP protocol specification for detailed information about status codes at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

Following is an example of a flow that is listening on the local address http://localhost:8080/mine and will send a response with the redirection code, instructing the client to go to http://mule.mulesoft.org/.

Note that you must set the exchange-pattern attribute to request-response. Otherwise, a response will be immediately returned while the request is placed on an internal queue.

To follow redirects when making an outbound HTTP call, use the followRedirect attribute:

Getting a Hash Map of POST body params

You can use the custom transformer

on your inbound endpoint to return the message properties as a hash map of name-value pairs. This transformer handles GET and POST with application/x-www-form-urlencoded content type.

For example:

Processing GET Query Parameters

GET parameters posted to an HTTP inbound endpoint are automatically available in the payload on the Mule Message in their raw form and the query parameters are also passed and stored as inbound-scoped headers of the Mule Message.

For example, the following flow creates a simple HTTP server:

Doing a request from a browser using the URL:

http://localhost:8081/echo?reverb=4&flange=2

Will result in a message payload of /echo?reverb=4&flange=2 and two additional inbound headers on the message reverb=4 and flange=2.

These headers can then be accessed using expressions i.e. #[header:INBOUND:reverb] which can be used by filters and routers or injected into your code.

Serving Static Content (since Mule 3.2)

The HTTP connector can be used as a web server to deliver static content such as images, HTML, JavaScript, CSS files etc. To enable this, configure a flow with an HTTP static-resource-handler:

The important attribute here is the resourceBase since it defines where on the local system that files will be served from. Typically, this should be set to ${app.home}/docroot, but it can point to any fully qualified location.

The default file allows you to specify the default resource to load if none is specified. If not set the default is index.html.

When developing your Mule application, the docroot directory should be located at <project.home>/src/main/app/docroot.

Content-Type Handling

The static-resource-handler uses the same mime type mapping system as the JDK, if you need to add your own mime type to file extension mappings, you need to add a the following file to your application <project home>/src/main/resources/META-INF/mime.types. With content similar to:

image/png                   png
text/plain                  txt cgi java

This maps the mime type to one or more file extensions.

HTTP Properties

When an HTTP request is processed in Mule, a Mule Message is created and the following HTTP information is persisted as inbound properties of the message.

• http.context.path: The context path of the endpoint being accessed. This is the path that the HTTP endpoint is listening on.
• http.context.uri: The context URI of the endpoint being accessed, it corresponds to the address of the endpoint.
• http.headers: A Map containing all the HTTP headers.
• http.method: The name of the HTTP method as used in the HTTP request line.
• http.query.params: A Map containing all the query parameters. It supports multiple values per key and both key and value are unescaped.
• http.query.string: The query string of the URL.
• http.request: The path and query portions of the URL being accessed.
• http.request.path: The path the URL being accessed. It does not include the query portion.
• http.relative.path: The relative path of the URI being accessed in relation to the context path.
• http.status: The status code associated with the latest response.
• http.version: The HTTP-Version.

To keep backward compatibility with previous versions of Mule, the headers and query parameters are also stored plain on the inbound properties. This behavior was improved in Mule 3.3 with the http.headers and http.query.params properties.

For example, giving the following HTTP GET request: http://localhost:8080/clients?min=1&max=10, the query parameters can be easily accessed by:

#[message.inboundProperties['min']] and #[message.inboundProperties['max']]

Examples

The following provides some common usage examples that will help you get an understanding of how you can use HTTP and Mule.

Configuration Reference

This connector also accepts all the attributes from the TCP connector.

Connector Allows Mule to communicate over HTTP. All parts of the HTTP spec are covered by Mule, so you can expect ETags to be honored as well as keep alive semantics and cookies.

Attributes of <connector...>

For example:

This connector also accepts all the attributes from the TCP connector.

Polling Connector Allows Mule to poll an external HTTP server and generate events from the result. This is useful for pull-only web services.

Attributes of <polling-connector...>

Rest Service Component Built-in RestServiceWrapper can be used to proxy REST style services as local Mule components.

Attributes of <rest-service-component...>

Child Elements of <rest-service-component...>

Inbound endpoint An inbound HTTP endpoint exposes a service over HTTP, essentially making it an HTTP server. If polling of a remote HTTP service is required, this endpoint should be configured with a polling HTTP connector.

Attributes of <inbound-endpoint...>

Child Elements of <inbound-endpoint...>

For example:

The HTTP inbound endpoint attributes override those specified for the default inbound endpoint attributes.

Outbound endpoint The HTTP outbound endpoint allows Mule to send requests to external servers or Mule inbound HTTP endpoints using the HTTP protocol.

Attributes of <outbound-endpoint...>

Child Elements of <outbound-endpoint...>

For example:

The HTTP outbound endpoint attributes override those specified for the default outbound endpoint attributes.

Endpoint Configures a 'global' HTTP endpoint that can be referenced by services. Services can augment the configuration defined in the global endpoint with local configuration elements.

Attributes of <endpoint...>

Child Elements of <endpoint...>

For example:

The HTTP endpoint attributes override those specified for the default global endpoint attributes.

Transformers

These are transformers specific to this transport. Note that these are added automatically to the Mule registry
at start up. When doing automatic transformations these will be included when searching for the correct
transformers.

Request wildcard filter (As of 2.2.2) The request-wildcard-filter element can be used to restrict the request by applying wildcard expressions to the URL.

Child Elements of <request-wildcard-filter...>