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:

Table of Contents

maxLevel	1

httpGetURL

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

Code Block

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

Info

title	Example - query

Code Block
/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.

Code Block

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

Info

title	Example - query

Code Block
/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.

Code Block

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

Info

title	Example - query

Code Block
/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.

Code Block

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

Info

title	Example - query

Code Block
/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.

Code Block

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

Info

title	Example - path

Code Block
/api/v2/doc

contentType

The MIME type of the content

Info

title	Example - contentType

Code Block
/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.

Code Block

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

Info

title	Example - path

Code Block
/api/v2/img

contentType

The MIME type of the content

Info

title	Example - contentType

Code Block
/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.

Code Block

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

Info

title	Example - path

Code Block
/api/v2/doc

contentType

The MIME type of the content

Info

title	Example - contentType

Code Block
/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.

Code Block

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

Info

title	Example - path

Code Block
/api/v2/img

contentType

The MIME type of the content

Info

title	Example - contentType

Code Block
/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.

Code Block
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

Info

title	Example - path

Code Block
/api

content The body of the request in bytearray format.

contentType

The MIME type of the content

Info

title	Example - contentType

Code Block
/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.

Code Block
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

Info

title	Example - contentType

Code Block
/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.

Code Block

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

Info

title	Example - contentType

Code Block
/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

Code Block
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

Info

title	Example - contentType

Code Block
/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.

Code Block

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

Info

title	Example - contentType

Code Block
/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.

Code Block
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.

Code Block
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.

Code Block
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.

Code Block
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

title	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.

Info

title	Example

Code Block
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.

Code Block

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

title	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.

Info

title	Example

Code Block
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

Anchor
JavaKeystore
JavaKeystore
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.

Info

title	Example - Setting Java keystore properties

Code Block

$ 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.

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

Note

title	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, Image Added 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:

Code Block

language	text
theme	Eclipse

$ 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
```

Info

title	Example - Setting properties to use a specific truststore

Code Block

$ 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.

Versions Compared

Old Version 1

New Version 2

Key

httpGetURL

httpBinaryGetURL

httpGetSecureURL

httpBinaryGetSecureURL

httpPostURL

httpBinaryPostURL

httpPostSecureURL

httpBinaryPostSecureURL

httpRequest

httpRequestBasicAuth

httpRequestSecureBasicAuth

httpRequestSecure

httpRequestDigestAuth

httpCreateMultipartBody

httpAddMultipartSegment

httpAddMultipartSegmentWithMapping

httpMultipartPostURL

httpMultipartPostSecureURL

TLS/SSL Encryption

Anchor
JavaKeystore
JavaKeystore
Configure Java Keystore for Secure URL Functions

Configure Java Truststore for Secure URL Functions

Page Comparison

Versions Compared

Old Version 1

New Version 2

Key

httpGetURL

httpBinaryGetURL

httpGetSecureURL

httpBinaryGetSecureURL

httpPostURL

httpBinaryPostURL

httpPostSecureURL

httpBinaryPostSecureURL

httpRequest

httpRequestBasicAuth

httpRequestSecureBasicAuth

httpRequestSecure

httpRequestDigestAuth

httpCreateMultipartBody

httpAddMultipartSegment

httpAddMultipartSegmentWithMapping

httpMultipartPostURL

httpMultipartPostSecureURL

TLS/SSL Encryption

AnchorJavaKeystoreJavaKeystoreConfigure Java Keystore for Secure URL Functions

Configure Java Truststore for Secure URL Functions

Anchor
JavaKeystore
JavaKeystore
Configure Java Keystore for Secure URL Functions