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 following functions for HTTP Client described here are:

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
`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
`query`	The query including path Example - query /api/v2/img/1 /api/v2/img?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	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.

string httpGetSecureURL
    ( 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
`query`	The query including path Example - query /api/v2/doc/1 /api/v2/doc?id=1
`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.

bytearray httpBinaryGetSecureURL
    ( 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
`query`	The query including path Example - query /api/v2/img/1 /api/v2/img?id=1
`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.

string httpPostURL
    ( string path,		
      string contentType,
      string content,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter	Description
`path`	The path Example - path /api/v2/doc
`contentType`	The MIME type of the content Example - contentType /application/json
`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.

bytearray httpBinaryPostURL
    ( string path,		
      string contentType,
      bytearray content,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter	Description
`path`	The path Example - path /api/v2/img
`contentType`	The MIME type of the content Example - contentType /application/octet-stream
`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.

string httpPostSecureURL
    ( string path,		
      string contentType,
      string content,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter	Description
`path`	The path Example - path /api/v2/doc
`contentType`	The MIME type of the content Example - contentType /application/json
`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.

bytearray httpBinaryPostSecureURL
    ( string path,		
      string contentType,
      bytearray content,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter	Description
`path`	The path Example - path /api/v2/img
`contentType`	The MIME type of the content Example - contentType /application/octet-stream
`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.

string httpRequest
    ( string method,		
      string host,
      string path,
      bytearray content,
      string contentType,
      list dynamicArgs)	//Opt

Parameter	Description
`method`	The HTTP method
`host`	The name or IP address of the HTTP server.
`path`	The path Example - path /api
content	The body of the request in bytearray format.
`contentType`	The MIME type of the content Example - contentType /application/json
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.

string httpRequestBasicAuth
    ( string method,		
      string url,
      map<string,string> header,
      string contentType,
      string content,
      int timeout,
      string username
      string password,
	  int connectTimeout)	//Optional

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 Example - contentType /application/json
`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.

string httpRequestSecureBasicAuth
    ( string method,		
      string url,
      map<string,string> header,
      string contentType,
      string content,
      int timeout,
      string username,
      string password,
	  int connectTimeout)	//Optional

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 Example - contentType /application/json
`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

string httpRequestSecure
    ( string method,		
      string url,
      map<string,string> header,
      string contentType,
      string content,
      int timeout,
	  int connectTimeout)	//Optional

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 Example - contentType /application/json
`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.

string httpRequestDigestAuth
    ( string method, 
      string url,
      map<string,string> header,
      string contentType,
      string content,
      int timeout,
      string username,
      string password,
      int connectTimeout, 			//Optional
      string realm) 				//Optional

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 Example - contentType /application/json
`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.

any httpCreateMultipartBody ( )

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.

void httpAddMultipartSegment
    ( any body,
      string filename,
      string contentType,
      bytearray content )

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.

void httpAddMultipartSegmentWithMapping
    ( any body,
      string keyName
      string filename,
      string contentType,
      bytearray content )

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.

bytearray httpMultipartPostURL
    ( string path,
      any body,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers) //Optional

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.

Note!

For optional parameters, you need to state null in case you state subsequent optional parameters. If there are no subsequent parameters, you do not have to state anything.

Example

httpMultipartPostURL( "mypath", mybody, ""myhost, 0, null, "myusername");

httpMultipartPostSecureURL

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

bytearray httpMultipartPostSecureURL
    ( string path,
      any body,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers) //Optional

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.

Note!

For optional parameters, you need to state null in case you state subsequent optional parameters. If there are no subsequent parameters, you do not have to state anything.

Example

httpMultipartPostSecureURL( "mypath", mybody, ""myhost, 0, null, "myusername");

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.

Example - Setting Java keystore properties

$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.keystore_location <location of the Keystore file>
$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.keystore_passphrase <DR encrypted password>

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.

keytool -keystore /var/opt/mz/HttpdExec.keystore -genkey -keyalg RSA

Note!

The Keystore passphrase must be the same as the passphrase used by the certificate.

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, 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:

$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.userdefined.truststore 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
```

Example - Setting properties to use a specific truststore

$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.truststore_location <location of the truststore file>
$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.truststore_passphrase <DR encrypted password>

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

HTTP Client Functions

httpGetURL

httpBinaryGetURL

httpGetSecureURL

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