HTTP transport enhancements

In Apama 10.3.1, we added support for HTTP redirects, cookie handling for requests, HTTP request decoding, and HTML form encoding to the HTTP client transport. We also added support for HTTP requests and HTML form decoding to the HTTP server transport.

HTTP redirect support in the HTTP client transport

The HTTP client transport now supports HTTP redirects transparently. To enable this, set the followRedirects configuration option to trueIf the URL you requested returns an HTTP redirect response, your request is made automatically on the URL to which you were redirected. For GET requests, this will be another GET request. POST and PUT requests will be converted to GET requests instead (this is standard behavior and a lot of REST APIs rely on this behavior).

The following configuration example shows how to define followRedirects in your HTTP client chain:

HTTP cookies support in the HTTP client transport

The HTTP client transport can now transparently handle HTTP cookies for requests so that you no longer need to handle them in EPL. To enable this, set the cookieJar configuration option to true. TheHTTP client then stores in memory all cookies received from the server and adds them to subsequent outgoing requests. Expired cookies are automatically removed from the internal cache. The HTTP client also honors additional cookie attributes such as pathexpiryand max-age.

The following configuration example shows how to define cookieJar in your HTTP client chain:

Gzip/deflate decoding support in the HTTP client transport

The HTTP client transport can now decode HTTP responses that have been encoded with gzip or deflate compression format. It is able to accept compressed responses from servers and will automatically decompress the result. No configuration is needed to turn this on, the transport always permits the server to send encoded responses.

If the server chooses to compress the body of the response with gzip or deflate compression format, the HTTP client transport will decompress the body of the response. Warnings will be logged for all unsupported content encodings.

Gzip/deflate decoding support in the HTTP server transport

The HTTP server transport can now decode HTTP requests that have been encoded with gzip or deflate compression format. No configuration is needed to turn this on. The decoding is based on the Content-Encoding header. If the client sends an encoded request, the HTTP server automatically decodes it. Warnings will be logged for all unsupported content encodings.

You can demonstrate the decoding with an HTTP server configuration like the one below. This configuration assumes that the Request event type has fields directly matching those in the JSON payload of the request.

You can then use curl to send the gzip-compressed HTTP request to the HTTP server transport, with the body of the HTTP request in JSON format:

The HTTP server transport will read the Content-Encoding header and automatically decompress the payload.

HTML form decoding support in the HTTP server transport

The HTTP server transport now supports HTML form decoding and can decode multipart/form-data or application/x-www-form-urlencoded media types to a dictionary payload.

Example: URL encoding

If the Content-Type header field contains the application/x-www-form-urlencoded media type, the request payload is decoded to a dictionary payload with string keys and string values.

The following configuration example for the HTTP server transport shows how you can make use of URL encoding:

The body of the HTTP request is directly decoded into a dictionary and mapped to a URLEncodedData event type. We’re also assuming here that the fields in the URLEncodedData event type match the fields in the form and no mapping is needed between them. You can also see that we don’t need a String codec and a JSON codec, since the transport is producing a dictionary payload directly.

The following code block shows the EPL event types and monitor code required to listen for the events from the above chain and then log the result:

You can then use curl to send HTTP request to the HTTP server transport, with the request body containing two form fields:

Example: multipart/form-data

If the Content-Type header field contains the multipart/form-data media type, the request payload is decoded to a dictionary payload with string keys and either string or binary values. For the parts that have binary data, additional metadata is created. This metadata contains the contentTypecharset or filename information for each binary part. You can get the metadata as follows:

metadata.http.form.name.contentTyp
metadata.http.form.name.charset
metadata.http.form.name.filename

where name corresponds to the data in payload.name.

The following configuration example for the HTTP server transport shows how you can use the Mapper codec to map the metadata of a binary form field.

The following code block shows the EPL event types and monitor code required to listen for the events from the above chain and then log the result:

You can then use curl to send an HTTP POST request to the HTTP server transport, with the request payload containing three form fields:

Please note that the correlator can’t directly understand binary components, you will need to decode them with a codec like the String codec (provided with Apama) or a custom codec that you write yourself.

HTML form encoding support in the HTTP client transport

The HTTP client transport now supports HTML form encoding and can encode a dictionary payload to either multipart/form-data or application/x-www-form-urlencoded media types.

To encode the request as multipart/form-data, you must set metadata.contentType to multipart/form-data and then map the payload to a dictionary with string keys and either string or binary payloads. You must use this method to send non-ASCII text or binary data. The binary data form fields should have the following additional metadata: filenamecontentType and charsetfilename is a required parameter. You can put these metadata items in a form dictionary as follows:

metadata.http.form.name.contentType
metadata.http.form.name.charset
metadata.http.form.name.filename

where name corresponds to the data in payload.name.

You can also encode the request as application/x-www-form-urlencoded by setting metadata.contentType to application/x-www-form-urlencoded and mapping the payload to a dictionary with string keys and values.

The following configuration shows how you can use the Mapper codec to map the metadata and payload:

The following is an example of an EPL application which shows the event types and monitor code for sending data with application/x-www-from-urlencoded and multipart/form-data.

Summary

The HTTP client transport can automatically handle HTTP redirects and HTTP cookies, and can encode HTML forms. The HTTP server transport can decode HTML forms. Both transports (HTTP client and HTTP server) support decompression.

For more information, see the following sections in the online documentation for Apama 10.3.1: “The HTTP Server Transport Connectivity Plug-in” and “The HTTP Client Transport Connectivity Plug-in”.

Feel free to post on our our stack exchange site with any questions you may have about this, or any other, topic.