The client functions are used to exchange data with a HTTP/HTTPS server. There are specific functions for GET and POST as well as functions for general HTTP requests. Either plain text or encrypted communication can be used. Basic authentication is supported, as well as the use of a keystore, and if required a truststore, for the functions with an encrypted communication channel.

The HTTP client functions also support the use of proxy, see HTTP Proxy Support for information on how to setup HTTP proxy support.

The following functions for HTTP Client described here are:

1 httpGetURL
2 httpBinaryGetURL
3 httpGetSecureURL
4 httpBinaryGetSecureURL
5 httpPostURL
6 httpBinaryPostURL
7 httpPostSecureURL
8 httpBinaryPostSecureURL
9 httpRequest
10 httpRequestBasicAuth
11 httpRequestSecureBasicAuth
12 httpRequestSecure
13 httpRequestDigestAuth
14 httpCreateMultipartBody
15 httpAddMultipartSegment
16 httpAddMultipartSegmentWithMapping
17 httpMultipartPostURL
18 httpMultipartPostSecureURL
19 TLS/SSL Encryption

httpGetURL

This function uses the GET method to retrieve content from an HTTP server.

string httpGetURL
    ( string query,		
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter	Description

Parameter	Description
`query`	The query including path Example - query `/api/v2/doc/1 /api/v2/doc?id=1`
`host`	The name or IP address where the HTTP server is running
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
`port`	The port number to contact the HTTP server on. Port 80 is used by default.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`headers`	Custom HTTP request headers.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	Content from the HTTP server. It will be `null` if any part of the communication fails.

httpBinaryGetURL

This function uses the GET method to retrieve binary content from an HTTP server.

bytearray httpBinaryGetURL
    ( string query,		
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter	Description

Parameter	Description
`query`	The query including path Example - query
`host`	The name or IP address where the HTTP server is running
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
`port`	The port number to contact the HTTP server on. Port 80 is used by default.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`headers`	Custom HTTP request headers.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	A bytearray from the HTTP server. It will be `null` if any part of the communication fails.

httpGetSecureURL

This function uses the GET method to retrieve content from an HTTPS server. The communication channel is encrypted.

Parameter	Description

Parameter	Description
`query`	The query including path Example - query
`host`	The name or IP address where the HTTPS server is running
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
`port`	The port number to contact the HTTPS server on. Port 443 is used by default.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`headers`	Custom HTTP request headers.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	Content from the HTTPS server. It will be `null` if any part of the communication fails.

See the section below, TLS/SSL Encryption.

httpBinaryGetSecureURL

This function uses the GET method to retrieve binary content from an HTTPS server. The communication channel is encrypted.

Parameter	Description

Parameter	Description
`query`	The query including path
`host`	The name or IP address where the HTTPS server is running
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
`port`	The port number to contact the HTTPS server on. Port 443 is used by default.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`headers`	Custom HTTP request headers.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	A bytearray from the HTTPS server. It will be `null` if any part of the communication fails.

See the section below, TLS/SSL Encryption.

httpPostURL

This function uses the POST method to send content to an HTTP server and receives the response.

Parameter	Description

Parameter	Description
`path`	The path
`contentType`	The MIME type of the content
`content`	The body of the request
`host`	The name or IP address where the HTTP server is running
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
`port`	The port number to contact the HTTP server on. Port 80 is used by default.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`headers`	Custom HTTP request headers.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	Content from the HTTP server. It will be `null` if any part of the communication fails.

httpBinaryPostURL

This function uses the POST method to send binary content to an HTTP server and receives the response.

Parameter	Description

Parameter	Description
`path`	The path
`contentType`	The MIME type of the content
`content`	The body of the request
`host`	The name or IP address where the HTTP server is running
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds.
`port`	The port number to contact the HTTP server on. Port 80 is used by default.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`headers`	Custom HTTP request headers.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	A bytearray from the HTTP server. It will be `null` if any part of the communication fails.

httpPostSecureURL

This function uses the POST method to send content to an HTTPS server and receives the response. The communication channel is encrypted.

Parameter	Description

Parameter	Description
`path`	The path
`contentType`	The MIME type of the content
`content`	The body of the request
`host`	The name or IP address where the HTTPS server is running
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds.
`port`	The port number to contact the HTTPS server on. Port 443 is used by default.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`headers`	Custom HTTP request headers.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	A document from the HTTP server. It will be `null` if any part of the communication fails.

See the section below, TLS/SSL Encryption.

httpBinaryPostSecureURL

This function uses the POST method to send binary content to an HTTP server and receives the response. The communication channel is encrypted.

Parameter	Description

Parameter	Description
`path`	The path
`contentType`	The MIME type of the content
`content`	The body of the request
`host`	The name or IP address where the HTTPS server is running
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds.
`port`	The port number to contact the HTTPS server on. Port 443 is used by default.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`headers`	Custom HTTP request headers.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	A bytearray from the HTTP server. It will be `null` if any part of the communication fails.

See the section below, TLS/SSL Encryption.

httpRequest

This function makes an HTTP request and uses the specified method, e g GET, POST, PUT etc.

Parameter	Description

Parameter	Description
`method`	The HTTP method
`url`	The host and port of the HTTP server, e g http://host:port
`header`	Key-value pairs containing request header fields
`path`	The path
content	The body of the request.
`contentType`	The MIME type of the content
dynamicArgs	The body of the request

httpRequestBasicAuth

This function makes an HTTP request with basic authentication and uses the specified method, e g GET, POST, PUT etc.

Parameter	Description

Parameter	Description
`method`	The HTTP method
`url`	The URL of the HTTP server
`header`	Key-value pairs containing request header fields
`contentType`	The MIME type of the content
`content`	The body of the request
`timeout`	The number of milliseconds to wait for a response. A timeout of 0 (zero) is interpreted as an infinite timeout.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	A response from the HTTP server. It will be `null` if any part of the communication fails.

httpRequestSecureBasicAuth

This function makes an HTTPS request with basic authentication and uses the specified method, e g GET, POST, PUT etc.

Parameter	Description

Parameter	Description
`method`	The HTTP method
`url`	The URL of the HTTPS server
`header`	Key-value pairs containing request header fields
`contentType`	The MIME type of the content
`content`	The body of the request
`timeout`	The number of milliseconds to wait for a response. A timeout of 0 (zero) is interpreted as an infinite timeout.
`username`	A username for an account on the HTTP server
`password`	Password associated with the username
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	A response from the HTTPS server. It will be `null` if any part of the communication fails.

See the section below, TLS/SSL Encryption.

httpRequestSecure

This function makes an HTTPS request and uses the specified method, e g GET, POST, PUT etc

Parameter	Description

Parameter	Description
`method`	The method to be performed on the HTTPS server identified by the URL
`url`	The URL of the HTTPS server
`header`	Key-value pairs containing request header fields
`contentType`	The MIME type of the content
`content`	The body of the request
`timeout`	The number of milliseconds to wait for a response. A timeout of 0 (zero) is interpreted as an infinite timeout.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
Returns	A response from the HTTPS server. It will be `null` if any part of the communication fails.

See the section below, TLS/SSL Encryption.

httpRequestDigestAuth

This function sends a request to the server using Digest Authentication.

Parameter	Description

Parameter	Description
`method`	The HTTP method
`url`	The URL of the HTTP server
`header`	Key-value pairs containing request header fields
`contentType`	The MIME type of the content
`content`	The body of the request
`username`	The username required for authentication
`password`	The password required for authentication
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
`connectTimeout`	The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds.
`realm`	The name of the realm
Returns	A response from the HTTP server. It will be null if any part of the communication fails.

httpCreateMultipartBody

This function creates a multipart body that can be used in HTTP requests that accept a body.

Parameter	Description

Parameter	Description
Returns	A multipart body for HTTP requests to which typed binary segments can be added.

httpAddMultipartSegment

This function adds a typed binary segment to a multipart body that has been created using httpAddMultipartBody function.

Parameter	Description

Parameter	Description
`body`	A multipart body created by using the `httpAddMultipartBody` function.
`filename`	The filename to be associated with the segment.
`contentType`	The MIME type of the content (according to RFC1341).
`content`	The binary content of the request.
Returns	Nothing

httpAddMultipartSegmentWithMapping

This function adds a typed binary segment to a multipart body that has been created using httpAddMultipartBody function and allows to specify a custom key name.

Parameter	Description

Parameter	Description
`body`	A multipart body created by using the `httpAddMultipartBody` function.
keyName	A custom key name that will be used for the fragment
`filename`	The filename to be associated with the segment.
`contentType`	The MIME type of the content (according to RFC1341).
`content`	The binary content of the request.
Returns	Nothing

httpMultipartPostURL

This function uses the POST method to send multipart binary contents to an HTTP server and receives the response.

Parameter	Description

Parameter	Description
`path`	The path on the server to which we should do the POST.
`body`	A multipart body created by using the `httpCreateMultipartBody` function and populated using the `httpAddMultipartSegment` function.
`host`	The name or IP address of the HTTPS server.
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds.
`port`	The port to be used for the HTTPS server. Port 80 is used by default.
`username`	Username for the account to be used on the HTTPS server.
`password`	Password for the account to be used on the HTTPS server.
`headers`	Custom HTTP request headers.
Returns	A bytearray from the HTTPS server. It will be null if any part of the communication fails.

httpMultipartPostSecureURL

This function uses the POST method to send multipart binary content to an HTTPS server and receive the response.

Parameter	Description

Parameter	Description
`path`	The path on the server to which we should do the POST.
`body`	A multipart body created by using the `httpCreateMultipartBody` function and populated using the `httpAddMultipartSegment` function.
`host`	The name or IP address of the HTTPS server.
`timeout`	The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds.
`port`	The port to be used for the HTTPS server. Port 80 is used by default.
`username`	Username for the account to be used on the HTTPS server.
`password`	Password for the account to be used on the HTTPS server.
`headers`	Custom HTTP request headers.
Returns	A bytearray from the HTTPS server. It will be null if any part of the communication fails.

TLS/SSL Encryption

The following functions require a keystore in order to work, and if required, the use of a truststore is supported:

httpGetSecureURL
httpBinaryGetSecureURL
httpPostSecureURL
httpBinaryPostSecureURL
httpRequestSecureBasicAuth
httpRequestSecure

Configure Java Keystore for Secure URL Functions

Keystore is used to store HTTP Client’s credential. This certificate is sent to a server for authentication if required.

To specify a Keystore file that you want to use, set the properties https.apl.keystore_location and https.apl.keystore_passphrase in the relevant ECs. See the example below on how to set these properties using the mzsh topo command.

If the two properties above are not set in the relevant Execution Context <pico>.conf, MZ Default Keystore is used.

The property https.apl.keystore_location represents the location of the keystore and the property https.apl.keystore_passphrase represents the passphrase for that keystore.

The following command can be used to create a keystore with the Java keytool program.

See the JVM product documentation for more information about how to use the keytool.

Configure Java Truststore for Secure URL Functions

A truststore is a keystore that is used when deciding on what to trust - truststore stores certificates from third parties. If you receive data from an entity that you already trust, and if you can verify that the entity is that which it claims to be, you can assume that the data does in fact come from that entity.

By Default, MediationZone uses its own truststore, which always trusts any server connection.

If you want to use a specific truststore, use the mzsh topo command to add the property https.apl.userdefined.truststore to the required ECs and set the value to true:

The default value of this property is false.

After setting the property https.apl.userdefined.truststore to true, if you want to use a specific truststore, use the mzsh topo command to set the following properties in the relevant ECs:

https.apl.truststore_location
https.apl.truststore_passphrase

If you do not set these two properties, the Java Default Truststore is used.

MediationZone Documentation 9.3

HTTP Client Functions

httpGetURL

Example - query

httpBinaryGetURL

Example - query

httpGetSecureURL

Example - query

httpBinaryGetSecureURL

httpPostURL

httpBinaryPostURL

httpPostSecureURL

httpBinaryPostSecureURL

httpRequest

httpRequestBasicAuth

httpRequestSecureBasicAuth

httpRequestSecure

httpRequestDigestAuth

httpCreateMultipartBody

httpAddMultipartSegment

httpAddMultipartSegmentWithMapping

httpMultipartPostURL

httpMultipartPostSecureURL

TLS/SSL Encryption

Configure Java Keystore for Secure URL Functions

Configure Java Truststore for Secure URL Functions