HTTP properties usability improvement

Motivation

This task aims to improve the user experience around HTTP properties. Currently when a Mule Message is created the HTTP properties are populated into the message inbound properties. This includes the following:

• HTTP headers
• Query parameters
• Request URI
• Request URI path
• Context path of the endpoint being accessed
• HTTP method
• Cookies
• HTTP Version
• HTTP Status

There is a big downside in the way this information is stored: every property is stored plain in the message inbound properties, there is no way to access all the HTTP headers or the query parameters.

Suggested Improvements:

1. Store all the HTTP headers encapsulated in a new inbound property called http.headers. This property represents a map with all the HTTP headers, enabling easy access to them through Mule's expression language.
2. Store all the query parameters encapsulated in a new inbound property called http.query.params. This property represents a map with all the query parameters received, enabling easy access to them through Mule's expression language.
3. Enable multiple values for the query parameters, returning a String when there is only one value for key or a List if there are multiple values for key. The same way as it is done by the HTTP transformers.
4. Unescape the query parameters. HTTP query parameters need to be escaped if they want to include special characters such as spaces or ampersands.
   This point is related to the JIRA issue MULE-5938
5. Provide a new HTTP inbound property called http.relative.path which will hold the relative path of the request according to the address of the endpoint being accessed.
   This property will be useful for REST resources routing.
6. Add a new http.query.string property. Currently the only way to obtain the query string is to parse the http.request

Migration impact, backwards compatibility issues

This usability improvement won't have any impact on the migration. Despite the new properties and functionality changes around the query parameters, the properties will still be stored plain in the message inbound properties. So they will still be accessible as before.

Documentation impact/update required

The HTTP transport reference documentation will need to be updated to reflect the new properties and explain how to access them.

Currently the HTTP Transport Reference documentation doesn't mention the HTTP properties available on the message once an HTTP request is received in Mule so a new section should be added before the Examples Section to describe the available properties.

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 has been 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']]

Impact on other projects

None

Example Use Case

The following code snippet shows how to expose a REST resource with Mule using the relative path to identify the resource. The query parameter is also accessed from the new http.headers property.